phaseC: extras/importers/ — 6 importers en Cercle 3 + 2 marqués experimental

Troisième phase de la refonte en 3 cercles. Cible : extraire les
importers (sources distantes IIIF, HuggingFace, HTR-United, Gallica,
eScriptorium + helpers HTTP) du package racine vers
``picarones/extras/importers/``.

Modules déplacés (6 fichiers, ~2600 lignes)
-------------------------------------------
``picarones/extras/importers/`` :
- ``_http.py`` helpers HTTP partagés (validate_http_url, download_url)
- ``iiif.py`` manifestes IIIF v2/v3 (Bodleian, BnF, Vatican)
- ``htr_united.py`` catalogue HTR-United (CC0, GitHub)
- ``gallica.py`` BnF Gallica (SRU + IIIF + OCR brut)
- ``huggingface.py`` ⚠ statut **experimental**
- ``escriptorium.py`` ⚠ statut **experimental**

Modules expérimentaux
---------------------
``huggingface`` et ``escriptorium`` émettent un ``UserWarning`` à
l'import :

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.

Justification :
- HuggingFace : 0 utilisateur réel, l'API ``datasets`` évolue
fréquemment, pas de tests d'intégration.
- eScriptorium : 1 test isolé (Sprint 8), pas validé sur instance
publique, statut prototype depuis le début.

Le warning ne casse rien (juste informatif). Si une institution
trouve l'API utile et la valide, on peut la promouvoir au statut
maintenu et retirer le warning.

Rétrocompatibilité absolue (6 shims de 16 lignes)
--------------------------------------------------
Imports historiques préservés :
from picarones.importers.iiif import IIIFImporter
from picarones.importers.gallica import GallicaClient
from picarones.importers._http import validate_http_url

Identité préservée — ``shim.X is extras.X`` (tests ``is`` vérifiés).

Note : ``picarones/importers/__init__.py`` reste inchangé. Il
réexporte des symboles depuis les shims, eux-mêmes chargeant depuis
``picarones.extras.importers.X``. Trois niveaux d'indirection mais
totalement transparents.

pyproject.toml — extra [importers]
----------------------------------
Nouvel extra ``picarones[importers]`` (vide pour l'instant — les
modules sont dans le package principal). Documente l'intention de
séparation future en package PyPI distinct. Inclus dans l'extra
``[all]``.

Validation 8/8 en sandbox
-------------------------
- 11 imports rétrocompat OK (4 importers maintenus + 1 helper HTTP +
1 importer expérimental, multipliés par leurs symboles publics).
- Identité shim ↔ nouveau chemin préservée (3 paires testées).
- huggingface : UserWarning experimental émis à l'import.
- escriptorium : UserWarning experimental émis à l'import.
- iiif : pas de warning (importer maintenu).
- ``picarones.importers/__init__.py`` continue à réexporter
IIIFImporter, GallicaClient, EScriptoriumClient via les shims.
- ``cli/_imports.py`` charge sans erreur.
- pyproject.toml : extra ``[importers]`` documenté.
- 6 shims minces (16 lignes chacun).

Tests
-----
+220 lignes dans tests/test_phaseC_migration.py organisés en 8 classes :
TestImportersRetrocompat, TestExtrasImportersPath,
TestIdentityThroughShim, TestExperimentalImporters,
TestImportersInitReexports, TestCliImportsCommand,
TestPyprojectExtra, TestOriginalsAreShims.

Bilan cumulé phases A + B + C
-----------------------------
- Cercle 3 contient maintenant 24 modules + 6 renderers
(4 academic + 1 governance + 8 historical + 6 importers
+ 4 + 2 renderers + 1 helper HTTP).
- Code Python en dehors de ``extras/`` allégé d'environ 7600 lignes
(déplacées, pas supprimées).
- Aucune fonctionnalité supprimée.

Phases suivantes
----------------
- Phase E : core/ → core/ (Cercle 1, ~15 modules) +
measurements/ (~30 modules Cercle 2).
- Phase D : docs/api-stable.md + test_public_api.py + version 2.0.

picarones/extras/importers/__init__.py

@@ -0,0 +1,27 @@
+"""Importeurs de corpus depuis sources distantes (Cercle 3).
+
+Phase C du chantier de refonte en 3 cercles.
+
+Importeurs livrés
+-----------------
+- :mod:`_http`         — helpers HTTP partagés (validate_http_url, download_url)
+- :mod:`iiif`          — manifestes IIIF v2/v3 (Bodleian, BnF, Vatican…)
+- :mod:`htr_united`    — datasets HTR-United (CC0, GitHub)
+- :mod:`gallica`       — BnF Gallica (SRU + IIIF + OCR brut)
+- :mod:`huggingface`   — datasets HuggingFace ⚠ **expérimental**
+- :mod:`escriptorium`  — projets eScriptorium ⚠ **expérimental**
+
+Modules expérimentaux
+---------------------
+``huggingface`` et ``escriptorium`` émettent un ``UserWarning`` à
+l'import. Ils sont fonctionnellement présents mais leur usage en
+production n'est pas garanti — l'API HuggingFace Datasets évolue
+fréquemment et eScriptorium n'a qu'un test isolé. À utiliser à vos
+risques jusqu'à ce qu'un cas d'usage institutionnel valide leur API.
+
+Plugin séparable
+----------------
+Distribué via l'extra pip ``picarones[importers]``. Les imports
+historiques ``from picarones.importers.iiif import ...`` restent
+fonctionnels via des fichiers-shims dans :mod:`picarones.importers`.
+"""

picarones/extras/importers/_http.py

@@ -0,0 +1,108 @@
+"""Helpers HTTP partagés par les importeurs IIIF / Gallica / HTR-United.
+
+Chantier 4 du plan d'évolution post-Sprint 97 — fusion Gallica vers IIIF.
+
+Auparavant les fonctions ``_validate_url`` et ``_download_url`` étaient
+dupliquées entre :mod:`picarones.importers.iiif` (lignes 310-344) et
+:mod:`picarones.importers.gallica` (lignes 125-155). Le module Gallica
+faisait 549 lignes dont une bonne partie réimplémentait les mêmes
+abstractions HTTP que IIIF (validation de schéma, retry exponentiel,
+gestion des codes HTTP).
+
+Ce module privé centralise ces helpers. Les deux importeurs (et tout
+nouveau importateur HTTP futur) les utilisent. Comportement public
+inchangé — uniquement de la factorisation.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+import urllib.error
+import urllib.request
+from typing import Optional
+from urllib.parse import urlparse
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_USER_AGENT = (
+    "Picarones/1.0 (OCR benchmark platform; "
+    "https://github.com/maribakulj/Picarones)"
+)
+
+
+def validate_http_url(url: str) -> None:
+    """Lève ``ValueError`` si le schéma de l'URL n'est pas http/https.
+
+    Garde-fou contre les URLs ``file://``, ``ftp://``, ``data:`` qui
+    permettraient à un manifeste IIIF malveillant de lire des fichiers
+    locaux ou de contourner la politique réseau.
+    """
+    parsed = urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        raise ValueError(
+            f"Schéma URL non autorisé '{parsed.scheme}' "
+            f"(seuls http/https sont acceptés) : {url}"
+        )
+
+
+def download_url(
+    url: str,
+    *,
+    retries: int = 4,
+    backoff: float = 2.0,
+    timeout: int = 60,
+    user_agent: str = _DEFAULT_USER_AGENT,
+    extra_headers: Optional[dict[str, str]] = None,
+) -> bytes:
+    """Télécharge une URL avec retry exponentiel.
+
+    Parameters
+    ----------
+    url:
+        URL à télécharger. Validée par :func:`validate_http_url`.
+    retries:
+        Nombre total de tentatives (défaut 4).
+    backoff:
+        Base du backoff exponentiel : attente = ``backoff ** attempt``
+        secondes (défaut 2.0 → 0, 2, 4, 8 s).
+    timeout:
+        Timeout HTTP par tentative en secondes (défaut 60).
+    user_agent:
+        Header ``User-Agent`` envoyé. Défaut : Picarones identifié.
+    extra_headers:
+        Headers supplémentaires (ex : ``{"Accept": "application/json"}``).
+
+    Raises
+    ------
+    ValueError
+        Si l'URL n'a pas un schéma autorisé.
+    RuntimeError
+        Si toutes les tentatives échouent.
+    """
+    validate_http_url(url)
+    headers = {"User-Agent": user_agent}
+    if extra_headers:
+        headers.update(extra_headers)
+    last_exc: Optional[Exception] = None
+    for attempt in range(retries):
+        if attempt > 0:
+            wait = backoff ** attempt
+            logger.debug(
+                "Retry %d/%d dans %.1fs — %s",
+                attempt, retries - 1, wait, url,
+            )
+            time.sleep(wait)
+        try:
+            req = urllib.request.Request(url, headers=headers)
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return resp.read()
+        except (urllib.error.URLError, urllib.error.HTTPError) as exc:
+            last_exc = exc
+            logger.warning("Erreur téléchargement %s : %s", url, exc)
+    raise RuntimeError(
+        f"Impossible de télécharger {url} après {retries} tentatives",
+    ) from last_exc
+
+
+__all__ = ["validate_http_url", "download_url"]

picarones/extras/importers/escriptorium.py

@@ -0,0 +1,553 @@
+"""Intégration eScriptorium — import et export via API REST.
+
+⚠ **Statut : expérimental** (phase C du chantier de refonte en 3 cercles).
+Ce module n'a qu'un test isolé (Sprint 8) et n'a pas été validé sur une
+instance eScriptorium publique. À utiliser à vos risques jusqu'à ce
+qu'un cas d'usage institutionnel valide l'API. Un ``UserWarning`` est
+émis à l'import.
+
+Fonctionnement
+--------------
+1. Authentification par token (settings → API key dans eScriptorium)
+2. Listing et import de projets, documents et transcriptions
+3. Export des résultats de benchmark Picarones comme couche OCR dans eScriptorium
+
+API eScriptorium
+----------------
+eScriptorium expose une API REST documentée à /api/.
+Les endpoints principaux utilisés ici :
+- GET  /api/projects/                → liste des projets
+- GET  /api/documents/               → liste des documents (filtrables par projet)
+- GET  /api/documents/{pk}/parts/    → liste des pages d'un document
+- GET  /api/documents/{pk}/parts/{pk}/transcriptions/  → transcriptions d'une page
+- POST /api/documents/{pk}/parts/{pk}/transcriptions/  → créer une couche OCR
+
+Usage
+-----
+>>> from picarones.importers.escriptorium import EScriptoriumClient
+>>> client = EScriptoriumClient("https://escriptorium.example.org", token="abc123")
+>>> projects = client.list_projects()
+>>> corpus = client.import_document(doc_id=42, transcription_layer="manual")
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.error
+import urllib.parse
+import urllib.request
+import warnings
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+
+# Émission du warning ``experimental`` à l'import. Phase C du chantier
+# de refonte — voir docstring du module ci-dessus.
+warnings.warn(
+    "picarones.extras.importers.escriptorium 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,
+)
+
+
+from picarones.core.corpus import Corpus, Document
+
+if TYPE_CHECKING:
+    from picarones.core.results import BenchmarkResult
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Structures de données eScriptorium
+# ---------------------------------------------------------------------------
+
+@dataclass
+class EScriptoriumProject:
+    """Représentation d'un projet eScriptorium."""
+    pk: int
+    name: str
+    slug: str
+    owner: str = ""
+    document_count: int = 0
+
+    def as_dict(self) -> dict:
+        return {
+            "pk": self.pk,
+            "name": self.name,
+            "slug": self.slug,
+            "owner": self.owner,
+            "document_count": self.document_count,
+        }
+
+
+@dataclass
+class EScriptoriumDocument:
+    """Représentation d'un document eScriptorium."""
+    pk: int
+    name: str
+    project: str = ""
+    part_count: int = 0
+    transcription_layers: list[str] = field(default_factory=list)
+
+    def as_dict(self) -> dict:
+        return {
+            "pk": self.pk,
+            "name": self.name,
+            "project": self.project,
+            "part_count": self.part_count,
+            "transcription_layers": self.transcription_layers,
+        }
+
+
+@dataclass
+class EScriptoriumPart:
+    """Une page (part) d'un document eScriptorium."""
+    pk: int
+    title: str
+    image_url: str
+    order: int = 0
+    transcriptions: list[dict] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Client API eScriptorium
+# ---------------------------------------------------------------------------
+
+class EScriptoriumClient:
+    """Client pour l'API REST d'eScriptorium.
+
+    Parameters
+    ----------
+    base_url:
+        URL racine de l'instance (ex : ``"https://escriptorium.example.org"``).
+    token:
+        Token d'authentification API (depuis Settings > API dans eScriptorium).
+    timeout:
+        Timeout HTTP en secondes.
+
+    Examples
+    --------
+    >>> client = EScriptoriumClient("https://escriptorium.example.org", token="abc123")
+    >>> projects = client.list_projects()
+    >>> corpus = client.import_document(42, transcription_layer="manual")
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        timeout: int = 30,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+
+    # ------------------------------------------------------------------
+    # HTTP helpers
+    # ------------------------------------------------------------------
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Token {self.token}",
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+
+    def _get(self, path: str, params: Optional[dict] = None) -> dict:
+        """Effectue une requête GET et retourne le JSON."""
+        url = f"{self.base_url}/api/{path.lstrip('/')}"
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+        req = urllib.request.Request(url, headers=self._headers())
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as exc:
+            raise RuntimeError(
+                f"eScriptorium API erreur {exc.code} sur {url}: {exc.reason}"
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise RuntimeError(
+                f"Impossible de joindre {self.base_url}: {exc.reason}"
+            ) from exc
+
+    def _post(self, path: str, payload: dict) -> dict:
+        """Effectue une requête POST avec payload JSON."""
+        url = f"{self.base_url}/api/{path.lstrip('/')}"
+        data = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(
+            url, data=data, headers=self._headers(), method="POST"
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                body = resp.read().decode("utf-8")
+                return json.loads(body) if body else {}
+        except urllib.error.HTTPError as exc:
+            raise RuntimeError(
+                f"eScriptorium API erreur {exc.code} sur {url}: {exc.reason}"
+            ) from exc
+        except urllib.error.URLError as exc:
+            raise RuntimeError(
+                f"Impossible de joindre {self.base_url}: {exc.reason}"
+            ) from exc
+
+    def _paginate(self, path: str, params: Optional[dict] = None) -> list[dict]:
+        """Parcourt toutes les pages de résultats paginés."""
+        results: list[dict] = []
+        current_params = dict(params or {})
+        current_params.setdefault("page_size", 100)
+        page_num = 1
+        while True:
+            current_params["page"] = page_num
+            data = self._get(path, current_params)
+            if isinstance(data, list):
+                results.extend(data)
+                break
+            results.extend(data.get("results", []))
+            if not data.get("next"):
+                break
+            page_num += 1
+        return results
+
+    # ------------------------------------------------------------------
+    # API publique
+    # ------------------------------------------------------------------
+
+    def test_connection(self) -> bool:
+        """Vérifie que l'URL et le token sont valides.
+
+        Returns
+        -------
+        bool
+            True si l'authentification réussit.
+        """
+        try:
+            self._get("projects/", {"page_size": 1})
+            return True
+        except RuntimeError:
+            return False
+
+    def list_projects(self) -> list[EScriptoriumProject]:
+        """Retourne la liste des projets accessibles.
+
+        Returns
+        -------
+        list[EScriptoriumProject]
+        """
+        raw = self._paginate("projects/")
+        projects = []
+        for item in raw:
+            projects.append(EScriptoriumProject(
+                pk=item["pk"],
+                name=item.get("name", ""),
+                slug=item.get("slug", ""),
+                owner=item.get("owner", {}).get("username", "") if isinstance(item.get("owner"), dict) else str(item.get("owner", "")),
+                document_count=item.get("documents_count", 0),
+            ))
+        return projects
+
+    def list_documents(
+        self,
+        project_pk: Optional[int] = None,
+    ) -> list[EScriptoriumDocument]:
+        """Retourne la liste des documents, filtrés par projet si fourni.
+
+        Parameters
+        ----------
+        project_pk:
+            PK du projet eScriptorium (optionnel).
+
+        Returns
+        -------
+        list[EScriptoriumDocument]
+        """
+        params: dict = {}
+        if project_pk is not None:
+            params["project"] = project_pk
+        raw = self._paginate("documents/", params)
+        docs = []
+        for item in raw:
+            layers = [
+                t.get("name", "") if isinstance(t, dict) else str(t)
+                for t in item.get("transcriptions", [])
+            ]
+            docs.append(EScriptoriumDocument(
+                pk=item["pk"],
+                name=item.get("name", ""),
+                project=str(item.get("project", "")),
+                part_count=item.get("parts_count", 0),
+                transcription_layers=layers,
+            ))
+        return docs
+
+    def list_parts(self, doc_pk: int) -> list[EScriptoriumPart]:
+        """Retourne les pages (parts) d'un document.
+
+        Parameters
+        ----------
+        doc_pk:
+            PK du document eScriptorium.
+
+        Returns
+        -------
+        list[EScriptoriumPart]
+        """
+        raw = self._paginate(f"documents/{doc_pk}/parts/")
+        parts = []
+        for item in raw:
+            parts.append(EScriptoriumPart(
+                pk=item["pk"],
+                title=item.get("title", "") or f"Part {item.get('order', 0) + 1}",
+                image_url=item.get("image", "") or "",
+                order=item.get("order", 0),
+            ))
+        return parts
+
+    def get_transcriptions(self, doc_pk: int, part_pk: int) -> list[dict]:
+        """Retourne les transcriptions disponibles pour une page.
+
+        Parameters
+        ----------
+        doc_pk:
+            PK du document.
+        part_pk:
+            PK de la page.
+
+        Returns
+        -------
+        list[dict]
+            Chaque dict contient ``{"name": str, "content": str}``.
+        """
+        raw = self._get(f"documents/{doc_pk}/parts/{part_pk}/transcriptions/")
+        if isinstance(raw, list):
+            return raw
+        return raw.get("results", [])
+
+    def import_document(
+        self,
+        doc_pk: int,
+        transcription_layer: str = "manual",
+        output_dir: Optional[str] = None,
+        download_images: bool = True,
+        show_progress: bool = True,
+    ) -> Corpus:
+        """Importe un document eScriptorium comme corpus Picarones.
+
+        Télécharge les images et récupère les transcriptions de la couche
+        spécifiée comme vérité terrain.
+
+        Parameters
+        ----------
+        doc_pk:
+            PK du document dans eScriptorium.
+        transcription_layer:
+            Nom de la couche de transcription à utiliser comme GT.
+        output_dir:
+            Dossier local pour les images téléchargées. Si None, les images
+            sont stockées en mémoire (pas de sauvegarde sur disque).
+        download_images:
+            Si True, télécharge les images dans output_dir.
+        show_progress:
+            Affiche une barre de progression tqdm.
+
+        Returns
+        -------
+        Corpus
+            Corpus Picarones avec documents et GT.
+        """
+        # Récupérer les métadonnées du document
+        doc_info = self._get(f"documents/{doc_pk}/")
+        doc_name = doc_info.get("name", f"document_{doc_pk}")
+
+        parts = self.list_parts(doc_pk)
+        if not parts:
+            raise ValueError(f"Aucune page trouvée dans le document {doc_pk}")
+
+        if show_progress:
+            try:
+                from tqdm import tqdm
+                iterator = tqdm(parts, desc=f"Import {doc_name}")
+            except ImportError:
+                iterator = iter(parts)
+        else:
+            iterator = iter(parts)
+
+        out_path: Optional[Path] = None
+        if output_dir and download_images:
+            out_path = Path(output_dir)
+            out_path.mkdir(parents=True, exist_ok=True)
+
+        documents: list[Document] = []
+        for part in iterator:
+            # Récupérer les transcriptions
+            transcriptions = self.get_transcriptions(doc_pk, part.pk)
+            gt_text = ""
+            for t in transcriptions:
+                layer_name = t.get("transcription", {}).get("name", "") if isinstance(t.get("transcription"), dict) else t.get("name", "")
+                if layer_name == transcription_layer or not transcription_layer:
+                    # Le contenu est dans "content" ou dans les lignes
+                    lines = t.get("lines", []) or []
+                    if lines:
+                        gt_text = "\n".join(
+                            line.get("content", "") or ""
+                            for line in lines
+                            if line.get("content")
+                        )
+                    else:
+                        gt_text = t.get("content", "") or ""
+                    break
+
+            # Image
+            image_path = part.image_url or f"escriptorium://doc{doc_pk}/part{part.pk}"
+            if out_path and part.image_url and download_images:
+                ext = Path(urllib.parse.urlparse(part.image_url).path).suffix or ".jpg"
+                local_img = out_path / f"part_{part.pk:05d}{ext}"
+                try:
+                    urllib.request.urlretrieve(part.image_url, local_img)
+                    image_path = str(local_img)
+                except Exception as exc:
+                    logger.warning("Impossible de télécharger l'image %s: %s", part.image_url, exc)
+
+                # Sauvegarder la GT
+                gt_path = out_path / f"part_{part.pk:05d}.gt.txt"
+                gt_path.write_text(gt_text, encoding="utf-8")
+
+            documents.append(Document(
+                doc_id=f"part_{part.pk:05d}",
+                image_path=image_path,
+                ground_truth=gt_text,
+                metadata={
+                    "source": "escriptorium",
+                    "doc_pk": doc_pk,
+                    "part_pk": part.pk,
+                    "part_title": part.title,
+                    "transcription_layer": transcription_layer,
+                },
+            ))
+
+        return Corpus(
+            name=doc_name,
+            source=f"{self.base_url}/document/{doc_pk}/",
+            documents=documents,
+            metadata={
+                "escriptorium_url": self.base_url,
+                "doc_pk": doc_pk,
+                "transcription_layer": transcription_layer,
+            },
+        )
+
+    def export_benchmark_as_layer(
+        self,
+        benchmark_result: "BenchmarkResult",
+        doc_pk: int,
+        engine_name: str,
+        layer_name: Optional[str] = None,
+        part_mapping: Optional[dict[str, int]] = None,
+    ) -> int:
+        """Exporte les résultats Picarones comme couche OCR dans eScriptorium.
+
+        Parameters
+        ----------
+        benchmark_result:
+            Résultats du benchmark Picarones.
+        doc_pk:
+            PK du document cible dans eScriptorium.
+        engine_name:
+            Nom du moteur dont on exporte les transcriptions.
+        layer_name:
+            Nom de la couche à créer (défaut : ``"picarones_{engine_name}"``).
+        part_mapping:
+            Correspondance ``doc_id → part_pk`` eScriptorium. Si None,
+            la correspondance est inférée depuis les métadonnées des documents.
+
+        Returns
+        -------
+        int
+            Nombre de pages exportées avec succès.
+        """
+        if layer_name is None:
+            layer_name = f"picarones_{engine_name}"
+
+        # Trouver le rapport du moteur
+        engine_report = None
+        for report in benchmark_result.engine_reports:
+            if report.engine_name == engine_name:
+                engine_report = report
+                break
+        if engine_report is None:
+            raise ValueError(f"Moteur '{engine_name}' introuvable dans les résultats.")
+
+        exported = 0
+        for doc_result in engine_report.document_results:
+            if doc_result.engine_error:
+                continue
+
+            # Déterminer le part_pk
+            part_pk: Optional[int] = None
+            if part_mapping and doc_result.doc_id in part_mapping:
+                part_pk = part_mapping[doc_result.doc_id]
+            else:
+                # Essayer d'extraire depuis doc_id (ex: "part_00042")
+                try:
+                    part_pk = int(doc_result.doc_id.replace("part_", "").lstrip("0") or "0")
+                except ValueError:
+                    logger.warning("Impossible de déterminer part_pk pour %s", doc_result.doc_id)
+                    continue
+
+            try:
+                self._post(
+                    f"documents/{doc_pk}/parts/{part_pk}/transcriptions/",
+                    {
+                        "name": layer_name,
+                        "content": doc_result.hypothesis,
+                        "source": "picarones",
+                    },
+                )
+                exported += 1
+                logger.debug("Exporté part %d → couche '%s'", part_pk, layer_name)
+            except RuntimeError as exc:
+                logger.warning("Erreur export part %d: %s", part_pk, exc)
+
+        return exported
+
+
+# ---------------------------------------------------------------------------
+# Interface de niveau module
+# ---------------------------------------------------------------------------
+
+def connect_escriptorium(
+    base_url: str,
+    token: str,
+    timeout: int = 30,
+) -> EScriptoriumClient:
+    """Crée et retourne un client eScriptorium authentifié.
+
+    Parameters
+    ----------
+    base_url:
+        URL de l'instance eScriptorium.
+    token:
+        Token API.
+    timeout:
+        Timeout HTTP.
+
+    Returns
+    -------
+    EScriptoriumClient
+
+    Raises
+    ------
+    RuntimeError
+        Si la connexion échoue (URL invalide, token incorrect, serveur inaccessible).
+    """
+    client = EScriptoriumClient(base_url, token, timeout)
+    if not client.test_connection():
+        raise RuntimeError(
+            f"Impossible de se connecter à {base_url}. "
+            "Vérifiez l'URL et le token API."
+        )
+    return client

picarones/extras/importers/gallica.py

@@ -0,0 +1,553 @@
+"""Import de corpus depuis Gallica (BnF) via l'API SRU et IIIF.
+
+Fonctionnement
+--------------
+1. Recherche dans Gallica par cote (ark), titre, auteur ou date via l'API SRU BnF
+2. Récupération des images via l'API IIIF Gallica
+3. Récupération de l'OCR Gallica existant (texte brut ou ALTO) comme concurrent de référence
+
+API utilisées
+-------------
+- SRU BnF : https://gallica.bnf.fr/SRU?operation=searchRetrieve&query=...
+- IIIF Gallica : https://gallica.bnf.fr/ark:/12148/{ark}/manifest.json
+- OCR texte brut : https://gallica.bnf.fr/ark:/12148/{ark}/f{n}.texteBrut
+- Métadonnées OAI-PMH : https://gallica.bnf.fr/services/OAIRecord?ark={ark}
+
+Usage
+-----
+>>> from picarones.importers.gallica import GallicaClient
+>>> client = GallicaClient()
+>>> results = client.search(title="Froissart", date_from=1380, date_to=1420, max_results=10)
+>>> corpus = client.import_document(results[0].ark, pages="1-5", include_gallica_ocr=True)
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from typing import Optional
+
+from picarones.core.corpus import Corpus
+
+logger = logging.getLogger(__name__)
+
+# Namespaces SRU/OAI
+_NS_SRU = "http://www.loc.gov/zing/srw/"
+_NS_DC = "http://purl.org/dc/elements/1.1/"
+_NS_OAI = "http://www.openarchives.org/OAI/2.0/"
+
+_GALLICA_BASE = "https://gallica.bnf.fr"
+_SRU_URL = f"{_GALLICA_BASE}/SRU"
+_IIIF_MANIFEST_TPL = f"{_GALLICA_BASE}/ark:/{{ark}}/manifest.json"
+_OCR_BRUT_TPL = f"{_GALLICA_BASE}/ark:/{{ark}}/f{{page}}.texteBrut"
+
+
+# ---------------------------------------------------------------------------
+# Structures de données
+# ---------------------------------------------------------------------------
+
+@dataclass
+class GallicaRecord:
+    """Un résultat de recherche Gallica."""
+    ark: str
+    """Identifiant ARK sans préfixe (ex: ``'12148/btv1b8453561w'``)."""
+    title: str
+    creator: str = ""
+    date: str = ""
+    description: str = ""
+    type_doc: str = ""
+    language: str = ""
+    rights: str = ""
+    has_ocr: bool = False
+    """True si Gallica fournit un OCR pour ce document."""
+
+    @property
+    def url(self) -> str:
+        return f"{_GALLICA_BASE}/ark:/12148/{self.ark}"
+
+    @property
+    def manifest_url(self) -> str:
+        return f"{_GALLICA_BASE}/ark:/12148/{self.ark}/manifest.json"
+
+    def as_dict(self) -> dict:
+        return {
+            "ark": self.ark,
+            "title": self.title,
+            "creator": self.creator,
+            "date": self.date,
+            "description": self.description,
+            "type_doc": self.type_doc,
+            "language": self.language,
+            "has_ocr": self.has_ocr,
+            "url": self.url,
+            "manifest_url": self.manifest_url,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Client Gallica
+# ---------------------------------------------------------------------------
+
+class GallicaClient:
+    """Client pour les APIs Gallica (SRU, IIIF, OCR texte brut).
+
+    Parameters
+    ----------
+    timeout:
+        Timeout HTTP en secondes.
+    delay_between_requests:
+        Délai en secondes entre chaque requête (pour respecter les conditions
+        d'utilisation Gallica).
+
+    Examples
+    --------
+    >>> client = GallicaClient()
+    >>> results = client.search(author="Froissart", max_results=5)
+    >>> for r in results:
+    ...     print(r.title, r.date)
+    >>> corpus = client.import_document(results[0].ark, pages="1-3")
+    """
+
+    def __init__(
+        self,
+        timeout: int = 30,
+        delay_between_requests: float = 0.5,
+    ) -> None:
+        self.timeout = timeout
+        self.delay = delay_between_requests
+
+    # Chantier 4 (post-Sprint 97) — fusion Gallica → IIIF :
+    # ``_validate_url`` et le fetch HTTP sont désormais factorisés
+    # dans :mod:`picarones.importers._http`. Avant ce chantier ces
+    # 30 lignes étaient dupliquées avec :mod:`iiif`. Le polite
+    # ``delay_between_requests`` reste ici (spécifique à la BnF).
+
+    @staticmethod
+    def _validate_url(url: str) -> None:
+        """Délègue à :func:`picarones.importers._http.validate_http_url`."""
+        from picarones.importers._http import validate_http_url
+        validate_http_url(url)
+
+    def _fetch_url(self, url: str) -> bytes:
+        """Télécharge le contenu d'une URL avec respect du polite delay BnF.
+
+        Délègue à :func:`picarones.importers._http.download_url` puis
+        applique ``self.delay`` (par défaut 0.5 s) entre les requêtes
+        pour respecter les conditions d'utilisation Gallica.
+        """
+        from picarones.importers._http import download_url
+        try:
+            return download_url(
+                url,
+                retries=1,
+                timeout=self.timeout,
+                user_agent="Picarones/1.0 (research tool)",
+            )
+        except RuntimeError as exc:
+            # Le helper retourne ``RuntimeError`` après retries épuisés.
+            # On re-emballe pour conserver le format de message historique
+            # attendu par les tests Gallica (« HTTP 404 sur ... »).
+            raise RuntimeError(str(exc)) from exc
+        finally:
+            if self.delay > 0:
+                time.sleep(self.delay)
+
+    def _build_sru_query(
+        self,
+        ark: Optional[str] = None,
+        title: Optional[str] = None,
+        author: Optional[str] = None,
+        date_from: Optional[int] = None,
+        date_to: Optional[int] = None,
+        doc_type: Optional[str] = None,
+        language: Optional[str] = None,
+    ) -> str:
+        """Construit une requête CQL pour l'API SRU BnF."""
+        clauses: list[str] = []
+
+        if ark:
+            # Recherche par identifiant ARK
+            clauses.append(f'dc.identifier any "{ark}"')
+        if title:
+            clauses.append(f'dc.title all "{title}"')
+        if author:
+            clauses.append(f'dc.creator all "{author}"')
+        if date_from and date_to:
+            clauses.append(f'dc.date >= "{date_from}" and dc.date <= "{date_to}"')
+        elif date_from:
+            clauses.append(f'dc.date >= "{date_from}"')
+        elif date_to:
+            clauses.append(f'dc.date <= "{date_to}"')
+        if doc_type:
+            clauses.append(f'dc.type all "{doc_type}"')
+        if language:
+            clauses.append(f'dc.language all "{language}"')
+
+        if not clauses:
+            return 'gallica all "document"'
+        return " and ".join(clauses)
+
+    def search(
+        self,
+        ark: Optional[str] = None,
+        title: Optional[str] = None,
+        author: Optional[str] = None,
+        date_from: Optional[int] = None,
+        date_to: Optional[int] = None,
+        doc_type: Optional[str] = None,
+        language: Optional[str] = None,
+        max_results: int = 20,
+    ) -> list[GallicaRecord]:
+        """Recherche dans Gallica via l'API SRU BnF.
+
+        Parameters
+        ----------
+        ark:
+            Identifiant ARK (ex : ``'12148/btv1b8453561w'``).
+        title:
+            Mots-clés dans le titre.
+        author:
+            Mots-clés dans l'auteur/créateur.
+        date_from:
+            Borne inférieure de date (année).
+        date_to:
+            Borne supérieure de date (année).
+        doc_type:
+            Type de document (``'monographie'``, ``'périodique'``, ``'manuscrit'``…).
+        language:
+            Code langue ISO 639 (``'fre'``, ``'lat'``, ``'ger'``…).
+        max_results:
+            Nombre maximum de résultats à retourner.
+
+        Returns
+        -------
+        list[GallicaRecord]
+            Liste des documents trouvés.
+        """
+        query = self._build_sru_query(
+            ark=ark,
+            title=title,
+            author=author,
+            date_from=date_from,
+            date_to=date_to,
+            doc_type=doc_type,
+            language=language,
+        )
+
+        params = urllib.parse.urlencode({
+            "operation": "searchRetrieve",
+            "version": "1.2",
+            "query": query,
+            "maximumRecords": min(max_results, 50),
+            "startRecord": 1,
+            "recordSchema": "unimarcXchange",
+        })
+        url = f"{_SRU_URL}?{params}"
+
+        try:
+            raw = self._fetch_url(url)
+        except RuntimeError as exc:
+            logger.error("Erreur recherche SRU Gallica: %s", exc)
+            return []
+
+        return self._parse_sru_response(raw, max_results)
+
+    def _parse_sru_response(self, xml_bytes: bytes, max_results: int) -> list[GallicaRecord]:
+        """Parse la réponse SRU XML de Gallica."""
+        records: list[GallicaRecord] = []
+        try:
+            root = ET.fromstring(xml_bytes)
+        except ET.ParseError as exc:
+            logger.error("Impossible de parser la réponse SRU: %s", exc)
+            return records
+
+        # Les enregistrements sont dans srw:records/srw:record/srw:recordData
+        for rec_elem in root.iter():
+            if rec_elem.tag.endswith("}record") or rec_elem.tag == "record":
+                record = self._parse_record_element(rec_elem)
+                if record:
+                    records.append(record)
+                if len(records) >= max_results:
+                    break
+
+        return records
+
+    def _parse_record_element(self, elem: ET.Element) -> Optional[GallicaRecord]:
+        """Extrait les métadonnées d'un enregistrement SRU."""
+        # Chercher les champs Dublin Core dans l'enregistrement
+        def find_text(tag_suffix: str) -> str:
+            for child in elem.iter():
+                if child.tag.endswith(tag_suffix) and child.text:
+                    return child.text.strip()
+            return ""
+
+        def find_all_text(tag_suffix: str) -> list[str]:
+            return [
+                child.text.strip()
+                for child in elem.iter()
+                if child.tag.endswith(tag_suffix) and child.text
+            ]
+
+        # Chercher l'ARK dans l'identifiant
+        identifiers = find_all_text("identifier")
+        ark = ""
+        for ident in identifiers:
+            # Format typique : "https://gallica.bnf.fr/ark:/12148/btv1b8453561w"
+            m = re.search(r"ark:/(\d+/\w+)", ident)
+            if m:
+                ark = m.group(1)
+                break
+
+        if not ark:
+            return None
+
+        title = find_text("title") or "Sans titre"
+        creator = find_text("creator")
+        date = find_text("date")
+
+        # Vérifier si OCR disponible (heuristique : type monographie/périodique généralement)
+        doc_types = find_all_text("type")
+        has_ocr = any(
+            t.lower() in ("monographie", "fascicule", "texte", "text")
+            for t in doc_types
+        )
+
+        return GallicaRecord(
+            ark=ark,
+            title=title,
+            creator=creator,
+            date=date,
+            description=find_text("description"),
+            type_doc=", ".join(doc_types),
+            language=find_text("language"),
+            has_ocr=has_ocr,
+        )
+
+    def get_ocr_text(self, ark: str, page: int) -> str:
+        """Récupère l'OCR Gallica d'une page spécifique (texte brut).
+
+        Parameters
+        ----------
+        ark:
+            Identifiant ARK (ex : ``'12148/btv1b8453561w'``).
+        page:
+            Numéro de page 1-based.
+
+        Returns
+        -------
+        str
+            Texte OCR Gallica pour cette page (peut être vide si non disponible).
+        """
+        url = _OCR_BRUT_TPL.format(ark=ark, page=page)
+        try:
+            raw = self._fetch_url(url)
+            text = raw.decode("utf-8", errors="replace").strip()
+            # Gallica retourne parfois du HTML pour les pages sans OCR
+            if text.startswith("<!") or "<html" in text[:100].lower():
+                return ""
+            return text
+        except RuntimeError as exc:
+            logger.debug("OCR non disponible pour %s f%d: %s", ark, page, exc)
+            return ""
+
+    def import_document(
+        self,
+        ark: str,
+        pages: str = "all",
+        output_dir: Optional[str] = None,
+        include_gallica_ocr: bool = True,
+        max_resolution: int = 0,
+        show_progress: bool = True,
+    ) -> Corpus:
+        """Importe un document Gallica comme corpus Picarones.
+
+        Utilise le manifeste IIIF Gallica pour lister les pages et télécharger
+        les images. L'OCR Gallica est optionnellement récupéré comme GT ou comme
+        transcription de référence.
+
+        Parameters
+        ----------
+        ark:
+            Identifiant ARK (ex : ``'12148/btv1b8453561w'``).
+        pages:
+            Sélecteur de pages (``'all'``, ``'1-10'``, ``'1,3,5'``…).
+        output_dir:
+            Dossier local pour stocker images et GT.
+        include_gallica_ocr:
+            Si True, récupère l'OCR Gallica comme texte de référence.
+        max_resolution:
+            Largeur maximale des images téléchargées (0 = maximum disponible).
+        show_progress:
+            Affiche une barre de progression.
+
+        Returns
+        -------
+        Corpus
+            Corpus avec images et OCR Gallica comme GT (si disponible).
+        """
+        from picarones.importers.iiif import IIIFImporter
+
+        manifest_url = f"{_GALLICA_BASE}/ark:/12148/{ark}/manifest.json"
+        logger.info("Import Gallica ARK %s via IIIF : %s", ark, manifest_url)
+
+        # Utiliser l'importeur IIIF existant pour les images
+        importer = IIIFImporter(manifest_url, max_resolution=max_resolution)
+        importer.load()
+
+        corpus = importer.import_corpus(
+            pages=pages,
+            output_dir=output_dir or f"./corpus_gallica_{ark.split('/')[-1]}/",
+            show_progress=show_progress,
+        )
+
+        # Enrichir avec l'OCR Gallica si demandé
+        if include_gallica_ocr:
+            selected_indices = importer.list_canvases(pages)
+            for i, doc in enumerate(corpus.documents):
+                page_num = selected_indices[i] + 1 if i < len(selected_indices) else i + 1
+                gallica_ocr = self.get_ocr_text(ark, page_num)
+                if gallica_ocr:
+                    doc.metadata["gallica_ocr"] = gallica_ocr
+                    # Si pas de GT manuscrite, utiliser l'OCR Gallica comme référence
+                    if not doc.ground_truth.strip():
+                        doc.ground_truth = gallica_ocr
+                        doc.metadata["gt_source"] = "gallica_ocr"
+
+        # Ajouter métadonnées Gallica
+        corpus.metadata.update({
+            "source": "gallica",
+            "ark": ark,
+            "manifest_url": manifest_url,
+            "gallica_url": f"{_GALLICA_BASE}/ark:/12148/{ark}",
+            "include_gallica_ocr": include_gallica_ocr,
+        })
+
+        return corpus
+
+    def get_metadata(self, ark: str) -> dict:
+        """Récupère les métadonnées OAI-PMH d'un document Gallica.
+
+        Parameters
+        ----------
+        ark:
+            Identifiant ARK.
+
+        Returns
+        -------
+        dict
+            Métadonnées Dublin Core du document.
+        """
+        url = f"{_GALLICA_BASE}/services/OAIRecord?ark=ark:/12148/{ark}"
+        try:
+            raw = self._fetch_url(url)
+            root = ET.fromstring(raw)
+        except (RuntimeError, ET.ParseError) as exc:
+            logger.error("Erreur métadonnées OAI %s: %s", ark, exc)
+            return {"ark": ark}
+
+        def find_text(tag_suffix: str) -> str:
+            for elem in root.iter():
+                if elem.tag.endswith(tag_suffix) and elem.text:
+                    return elem.text.strip()
+            return ""
+
+        return {
+            "ark": ark,
+            "title": find_text("title"),
+            "creator": find_text("creator"),
+            "date": find_text("date"),
+            "description": find_text("description"),
+            "subject": find_text("subject"),
+            "language": find_text("language"),
+            "type": find_text("type"),
+            "format": find_text("format"),
+            "source": find_text("source"),
+            "url": f"{_GALLICA_BASE}/ark:/12148/{ark}",
+        }
+
+
+# ---------------------------------------------------------------------------
+# Fonctions de commodité
+# ---------------------------------------------------------------------------
+
+def search_gallica(
+    title: Optional[str] = None,
+    author: Optional[str] = None,
+    ark: Optional[str] = None,
+    date_from: Optional[int] = None,
+    date_to: Optional[int] = None,
+    max_results: int = 20,
+) -> list[GallicaRecord]:
+    """Recherche rapide dans Gallica.
+
+    Crée un client temporaire et effectue une recherche.
+
+    Parameters
+    ----------
+    title, author, ark, date_from, date_to:
+        Critères de recherche.
+    max_results:
+        Nombre maximum de résultats.
+
+    Returns
+    -------
+    list[GallicaRecord]
+
+    Examples
+    --------
+    >>> results = search_gallica(title="Froissart", date_from=1380, date_to=1430)
+    >>> for r in results[:3]:
+    ...     print(r.title, r.ark)
+    """
+    client = GallicaClient()
+    return client.search(
+        ark=ark,
+        title=title,
+        author=author,
+        date_from=date_from,
+        date_to=date_to,
+        max_results=max_results,
+    )
+
+
+def import_gallica_document(
+    ark: str,
+    pages: str = "all",
+    output_dir: Optional[str] = None,
+    include_gallica_ocr: bool = True,
+) -> Corpus:
+    """Importe un document Gallica en une ligne.
+
+    Parameters
+    ----------
+    ark:
+        Identifiant ARK (``'12148/btv1b8453561w'`` ou URL complète).
+    pages:
+        Sélecteur de pages (``'all'``, ``'1-10'``…).
+    output_dir:
+        Dossier de sortie.
+    include_gallica_ocr:
+        Inclure l'OCR Gallica comme GT.
+
+    Returns
+    -------
+    Corpus
+    """
+    # Normaliser l'ARK (extraire depuis URL complète si besoin)
+    m = re.search(r"ark:/(\d+/\w+)", ark)
+    if m:
+        ark = m.group(1)
+
+    client = GallicaClient()
+    return client.import_document(
+        ark=ark,
+        pages=pages,
+        output_dir=output_dir,
+        include_gallica_ocr=include_gallica_ocr,
+    )

picarones/extras/importers/htr_united.py

@@ -0,0 +1,455 @@
+"""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:
+        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:
+        pass
+    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/extras/importers/huggingface.py

@@ -0,0 +1,445 @@
+"""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:
+            pass
+
+        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:
+                    pass
+
+            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/extras/importers/iiif.py

@@ -0,0 +1,565 @@
+"""Import de corpus depuis des manifestes IIIF v2 et v3.
+
+Fonctionnement
+--------------
+1. Téléchargement et parsing du manifeste JSON (v2 ou v3 auto-détecté)
+2. Extraction de la liste des canvases (pages) avec leurs URL d'image
+3. Sélection optionnelle d'un sous-ensemble de pages (ex : ``--pages 1-10``)
+4. Téléchargement des images dans un dossier local
+5. Création de fichiers GT vides (``.gt.txt``) à remplir manuellement,
+   OU chargement des annotations de transcription si présentes dans le manifeste
+6. Construction et retour d'un objet ``Corpus``
+
+Compatibilité
+-------------
+- IIIF Image API v2 et v3
+- Manifestes Presentation API v2 et v3
+- Instances : Gallica (BnF), Bodleian, British Library, BSB, e-codices,
+  Europeana, et tout entrepôt IIIF-compliant
+
+Utilisation
+-----------
+>>> from picarones.importers.iiif import IIIFImporter
+>>> importer = IIIFImporter("https://gallica.bnf.fr/ark:/12148/xxx/manifest.json")
+>>> corpus = importer.import_corpus(pages="1-10", output_dir="./corpus/")
+>>> print(f"{len(corpus)} documents téléchargés")
+
+Ou via la fonction de commodité :
+>>> from picarones.importers.iiif import import_iiif_manifest
+>>> corpus = import_iiif_manifest("https://...", pages="1-5", output_dir="./corpus/")
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator, Optional
+
+from picarones.core.corpus import Corpus, Document
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Parsing du sélecteur de pages
+# ---------------------------------------------------------------------------
+
+def parse_page_selector(pages: str, total: int) -> list[int]:
+    """Parse un sélecteur de pages en liste d'indices 0-based.
+
+    Formats acceptés :
+    - ``"1-10"``        → pages 1 à 10 (1-based)
+    - ``"1,3,5"``       → pages 1, 3 et 5
+    - ``"1-5,10,15-20"`` → combinaison
+    - ``"all"`` / ``""`` → toutes les pages
+
+    Parameters
+    ----------
+    pages:
+        Sélecteur de pages en chaîne de caractères.
+    total:
+        Nombre total de pages dans le manifeste.
+
+    Returns
+    -------
+    list[int]
+        Indices 0-based des pages sélectionnées, triés et dédoublonnés.
+
+    Raises
+    ------
+    ValueError
+        Si la syntaxe est invalide ou les numéros hors bornes.
+    """
+    if not pages or pages.strip().lower() == "all":
+        return list(range(total))
+
+    indices: set[int] = set()
+    for part in pages.split(","):
+        part = part.strip()
+        if "-" in part:
+            m = re.fullmatch(r"(\d+)-(\d+)", part)
+            if not m:
+                raise ValueError(f"Sélecteur de pages invalide : '{part}'")
+            start, end = int(m.group(1)), int(m.group(2))
+            if start < 1 or end > total or start > end:
+                raise ValueError(
+                    f"Plage {start}-{end} hors bornes (1–{total})"
+                )
+            indices.update(range(start - 1, end))
+        else:
+            n = int(part)
+            if n < 1 or n > total:
+                raise ValueError(f"Page {n} hors bornes (1–{total})")
+            indices.add(n - 1)
+    return sorted(indices)
+
+
+# ---------------------------------------------------------------------------
+# Données d'un canvas IIIF
+# ---------------------------------------------------------------------------
+
+@dataclass
+class IIIFCanvas:
+    """Représente un canvas (page) dans un manifeste IIIF."""
+
+    index: int          # position 0-based dans le manifeste
+    label: str          # étiquette lisible (ex : "f. 1r", "Page 1")
+    image_url: str      # URL de l'image pleine résolution
+    width: Optional[int] = None
+    height: Optional[int] = None
+    transcription: Optional[str] = None  # texte GT si annoté dans le manifeste
+
+
+# ---------------------------------------------------------------------------
+# Parseur de manifeste IIIF
+# ---------------------------------------------------------------------------
+
+class IIIFManifestParser:
+    """Parse un manifeste IIIF Presentation API v2 ou v3."""
+
+    def __init__(self, manifest: dict) -> None:
+        self._manifest = manifest
+        self._version = self._detect_version()
+
+    def _detect_version(self) -> int:
+        """Détecte la version du manifeste (2 ou 3)."""
+        context = self._manifest.get("@context", "")
+        if isinstance(context, list):
+            context = " ".join(context)
+        if "presentation/3" in context or self._manifest.get("type") == "Manifest":
+            return 3
+        return 2
+
+    @property
+    def version(self) -> int:
+        return self._version
+
+    @property
+    def label(self) -> str:
+        """Titre du manifeste."""
+        raw = self._manifest.get("label", "")
+        return _extract_label(raw)
+
+    @property
+    def attribution(self) -> str:
+        raw = self._manifest.get("attribution", self._manifest.get("requiredStatement", ""))
+        return _extract_label(raw)
+
+    def canvases(self) -> list[IIIFCanvas]:
+        """Retourne la liste des canvases du manifeste."""
+        if self._version == 3:
+            return self._parse_v3_canvases()
+        return self._parse_v2_canvases()
+
+    def _parse_v2_canvases(self) -> list[IIIFCanvas]:
+        canvases: list[IIIFCanvas] = []
+        sequences = self._manifest.get("sequences", [])
+        if not sequences:
+            return canvases
+        raw_canvases = sequences[0].get("canvases", [])
+        for i, canvas in enumerate(raw_canvases):
+            label = _extract_label(canvas.get("label", f"canvas_{i+1}"))
+            # Image principale : images[0].resource.@id ou service
+            images = canvas.get("images", [])
+            image_url = ""
+            if images:
+                resource = images[0].get("resource", {})
+                image_url = _best_image_url_v2(resource, canvas)
+
+            # Annotations de transcription (OA annotations)
+            transcription = _extract_v2_transcription(canvas)
+
+            canvases.append(IIIFCanvas(
+                index=i,
+                label=label,
+                image_url=image_url,
+                width=canvas.get("width"),
+                height=canvas.get("height"),
+                transcription=transcription,
+            ))
+        return canvases
+
+    def _parse_v3_canvases(self) -> list[IIIFCanvas]:
+        canvases: list[IIIFCanvas] = []
+        items = self._manifest.get("items", [])
+        for i, canvas in enumerate(items):
+            label = _extract_label(canvas.get("label", f"canvas_{i+1}"))
+            image_url = _best_image_url_v3(canvas)
+            transcription = _extract_v3_transcription(canvas)
+            canvases.append(IIIFCanvas(
+                index=i,
+                label=label,
+                image_url=image_url,
+                width=canvas.get("width"),
+                height=canvas.get("height"),
+                transcription=transcription,
+            ))
+        return canvases
+
+
+# ---------------------------------------------------------------------------
+# Helpers extraction URL et label
+# ---------------------------------------------------------------------------
+
+def _extract_label(raw: object) -> str:
+    """Extrait une chaîne lisible depuis les différents formats de label IIIF."""
+    if isinstance(raw, str):
+        return raw
+    if isinstance(raw, list) and raw:
+        return _extract_label(raw[0])
+    if isinstance(raw, dict):
+        # IIIF v3 : {"fr": ["titre"], "en": ["title"]}
+        for lang in ("fr", "en", "none", "@value"):
+            val = raw.get(lang, "")
+            if val:
+                if isinstance(val, list):
+                    return val[0] if val else ""
+                return str(val)
+        # Fallback: première valeur
+        for v in raw.values():
+            return _extract_label(v)
+    return str(raw) if raw else ""
+
+
+def _best_image_url_v2(resource: dict, canvas: dict) -> str:
+    """Construit l'URL d'image optimale depuis une ressource IIIF v2."""
+    # 1. URL directe de la ressource
+    direct = resource.get("@id", "")
+    if direct and not direct.endswith("/info.json"):
+        return direct
+
+    # 2. Via le service IIIF Image API
+    service = resource.get("service", {})
+    if isinstance(service, list) and service:
+        service = service[0]
+    service_id = service.get("@id", service.get("id", ""))
+    if service_id:
+        return f"{service_id.rstrip('/')}/full/max/0/default.jpg"
+
+    return direct
+
+
+def _best_image_url_v3(canvas: dict) -> str:
+    """Extrait l'URL d'image depuis un canvas IIIF v3."""
+    items = canvas.get("items", [])
+    for annotation_page in items:
+        for annotation in annotation_page.get("items", []):
+            body = annotation.get("body", {})
+            if isinstance(body, list):
+                body = body[0] if body else {}
+            # URL directe
+            url = body.get("id", body.get("@id", ""))
+            if url and body.get("type", "") == "Image":
+                return url
+            # Via service IIIF Image API
+            service = body.get("service", [])
+            if isinstance(service, dict):
+                service = [service]
+            for svc in service:
+                svc_id = svc.get("id", svc.get("@id", ""))
+                if svc_id:
+                    return f"{svc_id.rstrip('/')}/full/max/0/default.jpg"
+            if url:
+                return url
+    return ""
+
+
+def _extract_v2_transcription(canvas: dict) -> Optional[str]:
+    """Tente d'extraire le texte GT depuis les annotations OA d'un canvas v2."""
+    other_content = canvas.get("otherContent", [])
+    for oc in other_content:
+        if not isinstance(oc, dict):
+            continue
+        motivation = oc.get("motivation", "")
+        if "transcrib" in motivation.lower() or "supplementing" in motivation.lower():
+            resources = oc.get("resources", [])
+            texts = []
+            for res in resources:
+                body = res.get("resource", {})
+                if body.get("@type") == "cnt:ContentAsText":
+                    texts.append(body.get("chars", ""))
+            if texts:
+                return "\n".join(texts)
+    return None
+
+
+def _extract_v3_transcription(canvas: dict) -> Optional[str]:
+    """Tente d'extraire le texte GT depuis les annotations d'un canvas v3."""
+    annotations = canvas.get("annotations", [])
+    for ann_page in annotations:
+        items = ann_page.get("items", [])
+        for ann in items:
+            motivation = ann.get("motivation", "")
+            if "transcrib" in motivation.lower() or "supplementing" in motivation.lower():
+                body = ann.get("body", {})
+                if isinstance(body, dict) and body.get("type") == "TextualBody":
+                    return body.get("value", "")
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Téléchargement avec retry
+# ---------------------------------------------------------------------------
+
+# Chantier 4 (post-Sprint 97) — helpers HTTP factorisés dans
+# :mod:`picarones.importers._http`. Ces noms restent disponibles
+# depuis ``iiif`` (rétrocompat des tests qui les importent
+# directement, ex. test_sprint4_normalization_iiif).
+from picarones.importers._http import download_url as _download_url
+from picarones.importers._http import validate_http_url as _validate_url
+
+
+def _fetch_manifest(url: str) -> dict:
+    """Télécharge et parse un manifeste IIIF JSON."""
+    data = _download_url(url)
+    try:
+        return json.loads(data.decode("utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Manifeste IIIF invalide (JSON mal formé) : {url}") from exc
+
+
+# ---------------------------------------------------------------------------
+# Importeur principal
+# ---------------------------------------------------------------------------
+
+class IIIFImporter:
+    """Importe un corpus depuis un manifeste IIIF.
+
+    Parameters
+    ----------
+    manifest_url:
+        URL du manifeste IIIF (Presentation API v2 ou v3).
+    max_resolution:
+        Résolution maximale des images téléchargées (largeur en pixels).
+        0 = résolution maximale disponible.
+    """
+
+    def __init__(
+        self,
+        manifest_url: str,
+        max_resolution: int = 0,
+    ) -> None:
+        self.manifest_url = manifest_url
+        self.max_resolution = max_resolution
+        self._manifest: Optional[dict] = None
+        self._parser: Optional[IIIFManifestParser] = None
+
+    def load(self) -> "IIIFImporter":
+        """Télécharge et parse le manifeste."""
+        logger.info("Téléchargement du manifeste IIIF : %s", self.manifest_url)
+        self._manifest = _fetch_manifest(self.manifest_url)
+        self._parser = IIIFManifestParser(self._manifest)
+        logger.info(
+            "Manifeste chargé — version IIIF %d — titre : %s — %d canvas",
+            self._parser.version,
+            self._parser.label,
+            len(self._parser.canvases()),
+        )
+        return self
+
+    @property
+    def parser(self) -> IIIFManifestParser:
+        if self._parser is None:
+            self.load()
+        return self._parser  # type: ignore[return-value]
+
+    def list_canvases(self, pages: str = "all") -> list[IIIFCanvas]:
+        """Retourne la liste des canvases sélectionnés."""
+        all_canvases = self.parser.canvases()
+        indices = parse_page_selector(pages, len(all_canvases))
+        return [all_canvases[i] for i in indices]
+
+    def import_corpus(
+        self,
+        pages: str = "all",
+        output_dir: Optional[str | Path] = None,
+        show_progress: bool = True,
+    ) -> Corpus:
+        """Télécharge les images et construit un corpus Picarones.
+
+        Si les canvases contiennent des annotations de transcription (GT),
+        elles sont automatiquement sauvegardées dans les fichiers ``.gt.txt``.
+        Sinon, des fichiers ``.gt.txt`` vides sont créés.
+
+        Parameters
+        ----------
+        pages:
+            Sélecteur de pages (ex : ``"1-10"``, ``"1,3,5"``).
+        output_dir:
+            Dossier de destination pour les images et les GT.
+            Si None, le corpus est retourné en mémoire sans écriture disque.
+        show_progress:
+            Affiche une barre de progression tqdm.
+
+        Returns
+        -------
+        Corpus
+            Corpus prêt à être utilisé dans ``run_benchmark``.
+        """
+        canvases = self.list_canvases(pages)
+        if not canvases:
+            raise ValueError("Aucun canvas sélectionné.")
+
+        out_dir: Optional[Path] = Path(output_dir) if output_dir else None
+        if out_dir:
+            out_dir.mkdir(parents=True, exist_ok=True)
+
+        # Nom du corpus depuis le titre du manifeste
+        corpus_name = self.parser.label or "iiif_corpus"
+
+        documents: list[Document] = []
+        iterator: Iterator[IIIFCanvas] = iter(canvases)
+
+        if show_progress:
+            try:
+                from tqdm import tqdm
+                iterator = tqdm(canvases, desc="Import IIIF", unit="page")
+            except ImportError:
+                pass
+
+        for canvas in iterator:
+            doc_id = f"{_slugify(canvas.label) or f'canvas_{canvas.index+1:04d}'}"
+
+            if not canvas.image_url:
+                logger.warning("Canvas %s : pas d'URL d'image — ignoré.", canvas.label)
+                continue
+
+            # Ajuster la résolution si max_resolution est défini
+            image_url = self._adjust_resolution(canvas.image_url, canvas.width)
+
+            # Téléchargement de l'image
+            try:
+                image_bytes = _download_url(image_url)
+            except RuntimeError as exc:
+                logger.error("Canvas %s : erreur téléchargement : %s", canvas.label, exc)
+                continue
+
+            # Déterminer l'extension de l'image
+            ext = _guess_extension(image_url)
+
+            if out_dir:
+                # Sauvegarde sur disque
+                image_path = out_dir / f"{doc_id}{ext}"
+                image_path.write_bytes(image_bytes)
+
+                gt_path = out_dir / f"{doc_id}.gt.txt"
+                gt_text = canvas.transcription or ""
+                gt_path.write_text(gt_text, encoding="utf-8")
+
+                documents.append(Document(
+                    image_path=image_path,
+                    ground_truth=gt_text,
+                    doc_id=doc_id,
+                    metadata={"iiif_label": canvas.label, "canvas_index": canvas.index},
+                ))
+            else:
+                # Corpus en mémoire (image stockée comme chemin temporaire virtuel)
+                import tempfile
+                tmp = tempfile.NamedTemporaryFile(suffix=ext, delete=False)
+                tmp.write(image_bytes)
+                tmp.close()
+                documents.append(Document(
+                    image_path=Path(tmp.name),
+                    ground_truth=canvas.transcription or "",
+                    doc_id=doc_id,
+                    metadata={"iiif_label": canvas.label, "canvas_index": canvas.index},
+                ))
+
+        if not documents:
+            raise ValueError("Aucun document importé depuis le manifeste IIIF.")
+
+        logger.info("Import IIIF terminé : %d documents.", len(documents))
+
+        return Corpus(
+            name=corpus_name,
+            documents=documents,
+            source_path=self.manifest_url,
+            metadata={
+                "iiif_manifest_url": self.manifest_url,
+                "iiif_version": self.parser.version,
+                "iiif_attribution": self.parser.attribution,
+                "pages_selected": pages,
+            },
+        )
+
+    def _adjust_resolution(self, image_url: str, canvas_width: Optional[int]) -> str:
+        """Ajuste l'URL IIIF Image API pour respecter max_resolution."""
+        if not self.max_resolution or not canvas_width:
+            return image_url
+        if canvas_width <= self.max_resolution:
+            return image_url
+        # Remplacer /full/max/ ou /full/full/ par /full/{w},/
+        url = re.sub(
+            r"/full/(max|full)/",
+            f"/full/{self.max_resolution},/",
+            image_url,
+        )
+        return url
+
+
+# ---------------------------------------------------------------------------
+# Helpers utilitaires
+# ---------------------------------------------------------------------------
+
+def _slugify(text: str) -> str:
+    """Convertit un label IIIF en identifiant de fichier sûr."""
+    text = re.sub(r"[^\w\s-]", "", text.strip())
+    text = re.sub(r"[\s_-]+", "_", text)
+    return text[:60]
+
+
+def _guess_extension(url: str) -> str:
+    """Détermine l'extension de l'image depuis l'URL."""
+    url_lower = url.lower().split("?")[0]
+    for ext in (".jpg", ".jpeg", ".png", ".tif", ".tiff", ".webp"):
+        if url_lower.endswith(ext):
+            return ext
+    # Par défaut pour les URLs IIIF Image API
+    if "/default." in url_lower or "/native." in url_lower:
+        return ".jpg"
+    return ".jpg"
+
+
+# ---------------------------------------------------------------------------
+# Fonction de commodité
+# ---------------------------------------------------------------------------
+
+def import_iiif_manifest(
+    manifest_url: str,
+    pages: str = "all",
+    output_dir: Optional[str | Path] = None,
+    max_resolution: int = 0,
+    show_progress: bool = True,
+) -> Corpus:
+    """Importe un corpus depuis un manifeste IIIF en une seule ligne.
+
+    Parameters
+    ----------
+    manifest_url:
+        URL du manifeste IIIF (v2 ou v3).
+    pages:
+        Sélecteur de pages (ex : ``"1-10"``, ``"1,3,5"``). ``"all"`` par défaut.
+    output_dir:
+        Dossier de destination. Si None, corpus en mémoire.
+    max_resolution:
+        Résolution maximale (px). 0 = pas de limite.
+    show_progress:
+        Affiche une barre de progression.
+
+    Returns
+    -------
+    Corpus
+    """
+    importer = IIIFImporter(manifest_url, max_resolution=max_resolution)
+    importer.load()
+    return importer.import_corpus(
+        pages=pages,
+        output_dir=output_dir,
+        show_progress=show_progress,
+    )

picarones/importers/_http.py

@@ -1,108 +1,17 @@
-"""Helpers HTTP partagés par les importeurs IIIF / Gallica / HTR-United.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.extras.importers._http`.
 
-Chantier 4 du plan d'évolution post-Sprint 97 — fusion Gallica vers IIIF.
+Phase C du chantier de refonte en 3 cercles (architecture-cercles.md).
+Cet importeur est désormais en Cercle 3 (``extras/importers/``). L'alias
+ici permet aux imports historiques (``from picarones.importers._http
+import ...``) de continuer à fonctionner.
 
-Auparavant les fonctions ``_validate_url`` et ``_download_url`` étaient
-dupliquées entre :mod:`picarones.importers.iiif` (lignes 310-344) et
-:mod:`picarones.importers.gallica` (lignes 125-155). Le module Gallica
-faisait 549 lignes dont une bonne partie réimplémentait les mêmes
-abstractions HTTP que IIIF (validation de schéma, retry exponentiel,
-gestion des codes HTTP).
-
-Ce module privé centralise ces helpers. Les deux importeurs (et tout
-nouveau importateur HTTP futur) les utilisent. Comportement public
-inchangé — uniquement de la factorisation.
+Voir :doc:`docs/architecture-cercles.md` et l'extra
+``picarones[importers]`` du ``pyproject.toml``.
 """
 
-from __future__ import annotations
-
-import logging
-import time
-import urllib.error
-import urllib.request
-from typing import Optional
-from urllib.parse import urlparse
-
-logger = logging.getLogger(__name__)
-
-_DEFAULT_USER_AGENT = (
-    "Picarones/1.0 (OCR benchmark platform; "
-    "https://github.com/maribakulj/Picarones)"
-)
-
-
-def validate_http_url(url: str) -> None:
-    """Lève ``ValueError`` si le schéma de l'URL n'est pas http/https.
-
-    Garde-fou contre les URLs ``file://``, ``ftp://``, ``data:`` qui
-    permettraient à un manifeste IIIF malveillant de lire des fichiers
-    locaux ou de contourner la politique réseau.
-    """
-    parsed = urlparse(url)
-    if parsed.scheme not in ("http", "https"):
-        raise ValueError(
-            f"Schéma URL non autorisé '{parsed.scheme}' "
-            f"(seuls http/https sont acceptés) : {url}"
-        )
-
-
-def download_url(
-    url: str,
-    *,
-    retries: int = 4,
-    backoff: float = 2.0,
-    timeout: int = 60,
-    user_agent: str = _DEFAULT_USER_AGENT,
-    extra_headers: Optional[dict[str, str]] = None,
-) -> bytes:
-    """Télécharge une URL avec retry exponentiel.
-
-    Parameters
-    ----------
-    url:
-        URL à télécharger. Validée par :func:`validate_http_url`.
-    retries:
-        Nombre total de tentatives (défaut 4).
-    backoff:
-        Base du backoff exponentiel : attente = ``backoff ** attempt``
-        secondes (défaut 2.0 → 0, 2, 4, 8 s).
-    timeout:
-        Timeout HTTP par tentative en secondes (défaut 60).
-    user_agent:
-        Header ``User-Agent`` envoyé. Défaut : Picarones identifié.
-    extra_headers:
-        Headers supplémentaires (ex : ``{"Accept": "application/json"}``).
-
-    Raises
-    ------
-    ValueError
-        Si l'URL n'a pas un schéma autorisé.
-    RuntimeError
-        Si toutes les tentatives échouent.
-    """
-    validate_http_url(url)
-    headers = {"User-Agent": user_agent}
-    if extra_headers:
-        headers.update(extra_headers)
-    last_exc: Optional[Exception] = None
-    for attempt in range(retries):
-        if attempt > 0:
-            wait = backoff ** attempt
-            logger.debug(
-                "Retry %d/%d dans %.1fs — %s",
-                attempt, retries - 1, wait, url,
-            )
-            time.sleep(wait)
-        try:
-            req = urllib.request.Request(url, headers=headers)
-            with urllib.request.urlopen(req, timeout=timeout) as resp:
-                return resp.read()
-        except (urllib.error.URLError, urllib.error.HTTPError) as exc:
-            last_exc = exc
-            logger.warning("Erreur téléchargement %s : %s", url, exc)
-    raise RuntimeError(
-        f"Impossible de télécharger {url} après {retries} tentatives",
-    ) from last_exc
-
+from picarones.extras.importers._http import *  # noqa: F401, F403
 
-__all__ = ["validate_http_url", "download_url"]
+import picarones.extras.importers._http as _module
+__all__ = getattr(_module, "__all__", [
+    name for name in dir(_module) if not name.startswith("_")
+])

picarones/importers/escriptorium.py

@@ -1,534 +1,17 @@
-"""Intégration eScriptorium — import et export via API REST.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.extras.importers.escriptorium`.
 
-Fonctionnement
---------------
-1. Authentification par token (settings → API key dans eScriptorium)
-2. Listing et import de projets, documents et transcriptions
-3. Export des résultats de benchmark Picarones comme couche OCR dans eScriptorium
+Phase C du chantier de refonte en 3 cercles (architecture-cercles.md).
+Cet importeur est désormais en Cercle 3 (``extras/importers/``). L'alias
+ici permet aux imports historiques (``from picarones.importers.escriptorium
+import ...``) de continuer à fonctionner.
 
-API eScriptorium
-----------------
-eScriptorium expose une API REST documentée à /api/.
-Les endpoints principaux utilisés ici :
-- GET  /api/projects/                → liste des projets
-- GET  /api/documents/               → liste des documents (filtrables par projet)
-- GET  /api/documents/{pk}/parts/    → liste des pages d'un document
-- GET  /api/documents/{pk}/parts/{pk}/transcriptions/  → transcriptions d'une page
-- POST /api/documents/{pk}/parts/{pk}/transcriptions/  → créer une couche OCR
-
-Usage
------
->>> from picarones.importers.escriptorium import EScriptoriumClient
->>> client = EScriptoriumClient("https://escriptorium.example.org", token="abc123")
->>> projects = client.list_projects()
->>> corpus = client.import_document(doc_id=42, transcription_layer="manual")
+Voir :doc:`docs/architecture-cercles.md` et l'extra
+``picarones[importers]`` du ``pyproject.toml``.
 """
 
-from __future__ import annotations
-
-import json
-import logging
-import urllib.error
-import urllib.parse
-import urllib.request
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import TYPE_CHECKING, Optional
-
-from picarones.core.corpus import Corpus, Document
-
-if TYPE_CHECKING:
-    from picarones.core.results import BenchmarkResult
-
-logger = logging.getLogger(__name__)
-
-# ---------------------------------------------------------------------------
-# Structures de données eScriptorium
-# ---------------------------------------------------------------------------
-
-@dataclass
-class EScriptoriumProject:
-    """Représentation d'un projet eScriptorium."""
-    pk: int
-    name: str
-    slug: str
-    owner: str = ""
-    document_count: int = 0
-
-    def as_dict(self) -> dict:
-        return {
-            "pk": self.pk,
-            "name": self.name,
-            "slug": self.slug,
-            "owner": self.owner,
-            "document_count": self.document_count,
-        }
-
-
-@dataclass
-class EScriptoriumDocument:
-    """Représentation d'un document eScriptorium."""
-    pk: int
-    name: str
-    project: str = ""
-    part_count: int = 0
-    transcription_layers: list[str] = field(default_factory=list)
-
-    def as_dict(self) -> dict:
-        return {
-            "pk": self.pk,
-            "name": self.name,
-            "project": self.project,
-            "part_count": self.part_count,
-            "transcription_layers": self.transcription_layers,
-        }
-
-
-@dataclass
-class EScriptoriumPart:
-    """Une page (part) d'un document eScriptorium."""
-    pk: int
-    title: str
-    image_url: str
-    order: int = 0
-    transcriptions: list[dict] = field(default_factory=list)
-
-
-# ---------------------------------------------------------------------------
-# Client API eScriptorium
-# ---------------------------------------------------------------------------
-
-class EScriptoriumClient:
-    """Client pour l'API REST d'eScriptorium.
-
-    Parameters
-    ----------
-    base_url:
-        URL racine de l'instance (ex : ``"https://escriptorium.example.org"``).
-    token:
-        Token d'authentification API (depuis Settings > API dans eScriptorium).
-    timeout:
-        Timeout HTTP en secondes.
-
-    Examples
-    --------
-    >>> client = EScriptoriumClient("https://escriptorium.example.org", token="abc123")
-    >>> projects = client.list_projects()
-    >>> corpus = client.import_document(42, transcription_layer="manual")
-    """
-
-    def __init__(
-        self,
-        base_url: str,
-        token: str,
-        timeout: int = 30,
-    ) -> None:
-        self.base_url = base_url.rstrip("/")
-        self.token = token
-        self.timeout = timeout
-
-    # ------------------------------------------------------------------
-    # HTTP helpers
-    # ------------------------------------------------------------------
-
-    def _headers(self) -> dict[str, str]:
-        return {
-            "Authorization": f"Token {self.token}",
-            "Accept": "application/json",
-            "Content-Type": "application/json",
-        }
-
-    def _get(self, path: str, params: Optional[dict] = None) -> dict:
-        """Effectue une requête GET et retourne le JSON."""
-        url = f"{self.base_url}/api/{path.lstrip('/')}"
-        if params:
-            url += "?" + urllib.parse.urlencode(params)
-        req = urllib.request.Request(url, headers=self._headers())
-        try:
-            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
-                return json.loads(resp.read().decode("utf-8"))
-        except urllib.error.HTTPError as exc:
-            raise RuntimeError(
-                f"eScriptorium API erreur {exc.code} sur {url}: {exc.reason}"
-            ) from exc
-        except urllib.error.URLError as exc:
-            raise RuntimeError(
-                f"Impossible de joindre {self.base_url}: {exc.reason}"
-            ) from exc
-
-    def _post(self, path: str, payload: dict) -> dict:
-        """Effectue une requête POST avec payload JSON."""
-        url = f"{self.base_url}/api/{path.lstrip('/')}"
-        data = json.dumps(payload).encode("utf-8")
-        req = urllib.request.Request(
-            url, data=data, headers=self._headers(), method="POST"
-        )
-        try:
-            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
-                body = resp.read().decode("utf-8")
-                return json.loads(body) if body else {}
-        except urllib.error.HTTPError as exc:
-            raise RuntimeError(
-                f"eScriptorium API erreur {exc.code} sur {url}: {exc.reason}"
-            ) from exc
-        except urllib.error.URLError as exc:
-            raise RuntimeError(
-                f"Impossible de joindre {self.base_url}: {exc.reason}"
-            ) from exc
-
-    def _paginate(self, path: str, params: Optional[dict] = None) -> list[dict]:
-        """Parcourt toutes les pages de résultats paginés."""
-        results: list[dict] = []
-        current_params = dict(params or {})
-        current_params.setdefault("page_size", 100)
-        page_num = 1
-        while True:
-            current_params["page"] = page_num
-            data = self._get(path, current_params)
-            if isinstance(data, list):
-                results.extend(data)
-                break
-            results.extend(data.get("results", []))
-            if not data.get("next"):
-                break
-            page_num += 1
-        return results
-
-    # ------------------------------------------------------------------
-    # API publique
-    # ------------------------------------------------------------------
-
-    def test_connection(self) -> bool:
-        """Vérifie que l'URL et le token sont valides.
-
-        Returns
-        -------
-        bool
-            True si l'authentification réussit.
-        """
-        try:
-            self._get("projects/", {"page_size": 1})
-            return True
-        except RuntimeError:
-            return False
-
-    def list_projects(self) -> list[EScriptoriumProject]:
-        """Retourne la liste des projets accessibles.
-
-        Returns
-        -------
-        list[EScriptoriumProject]
-        """
-        raw = self._paginate("projects/")
-        projects = []
-        for item in raw:
-            projects.append(EScriptoriumProject(
-                pk=item["pk"],
-                name=item.get("name", ""),
-                slug=item.get("slug", ""),
-                owner=item.get("owner", {}).get("username", "") if isinstance(item.get("owner"), dict) else str(item.get("owner", "")),
-                document_count=item.get("documents_count", 0),
-            ))
-        return projects
-
-    def list_documents(
-        self,
-        project_pk: Optional[int] = None,
-    ) -> list[EScriptoriumDocument]:
-        """Retourne la liste des documents, filtrés par projet si fourni.
-
-        Parameters
-        ----------
-        project_pk:
-            PK du projet eScriptorium (optionnel).
-
-        Returns
-        -------
-        list[EScriptoriumDocument]
-        """
-        params: dict = {}
-        if project_pk is not None:
-            params["project"] = project_pk
-        raw = self._paginate("documents/", params)
-        docs = []
-        for item in raw:
-            layers = [
-                t.get("name", "") if isinstance(t, dict) else str(t)
-                for t in item.get("transcriptions", [])
-            ]
-            docs.append(EScriptoriumDocument(
-                pk=item["pk"],
-                name=item.get("name", ""),
-                project=str(item.get("project", "")),
-                part_count=item.get("parts_count", 0),
-                transcription_layers=layers,
-            ))
-        return docs
-
-    def list_parts(self, doc_pk: int) -> list[EScriptoriumPart]:
-        """Retourne les pages (parts) d'un document.
-
-        Parameters
-        ----------
-        doc_pk:
-            PK du document eScriptorium.
-
-        Returns
-        -------
-        list[EScriptoriumPart]
-        """
-        raw = self._paginate(f"documents/{doc_pk}/parts/")
-        parts = []
-        for item in raw:
-            parts.append(EScriptoriumPart(
-                pk=item["pk"],
-                title=item.get("title", "") or f"Part {item.get('order', 0) + 1}",
-                image_url=item.get("image", "") or "",
-                order=item.get("order", 0),
-            ))
-        return parts
-
-    def get_transcriptions(self, doc_pk: int, part_pk: int) -> list[dict]:
-        """Retourne les transcriptions disponibles pour une page.
-
-        Parameters
-        ----------
-        doc_pk:
-            PK du document.
-        part_pk:
-            PK de la page.
-
-        Returns
-        -------
-        list[dict]
-            Chaque dict contient ``{"name": str, "content": str}``.
-        """
-        raw = self._get(f"documents/{doc_pk}/parts/{part_pk}/transcriptions/")
-        if isinstance(raw, list):
-            return raw
-        return raw.get("results", [])
-
-    def import_document(
-        self,
-        doc_pk: int,
-        transcription_layer: str = "manual",
-        output_dir: Optional[str] = None,
-        download_images: bool = True,
-        show_progress: bool = True,
-    ) -> Corpus:
-        """Importe un document eScriptorium comme corpus Picarones.
-
-        Télécharge les images et récupère les transcriptions de la couche
-        spécifiée comme vérité terrain.
-
-        Parameters
-        ----------
-        doc_pk:
-            PK du document dans eScriptorium.
-        transcription_layer:
-            Nom de la couche de transcription à utiliser comme GT.
-        output_dir:
-            Dossier local pour les images téléchargées. Si None, les images
-            sont stockées en mémoire (pas de sauvegarde sur disque).
-        download_images:
-            Si True, télécharge les images dans output_dir.
-        show_progress:
-            Affiche une barre de progression tqdm.
-
-        Returns
-        -------
-        Corpus
-            Corpus Picarones avec documents et GT.
-        """
-        # Récupérer les métadonnées du document
-        doc_info = self._get(f"documents/{doc_pk}/")
-        doc_name = doc_info.get("name", f"document_{doc_pk}")
-
-        parts = self.list_parts(doc_pk)
-        if not parts:
-            raise ValueError(f"Aucune page trouvée dans le document {doc_pk}")
-
-        if show_progress:
-            try:
-                from tqdm import tqdm
-                iterator = tqdm(parts, desc=f"Import {doc_name}")
-            except ImportError:
-                iterator = iter(parts)
-        else:
-            iterator = iter(parts)
-
-        out_path: Optional[Path] = None
-        if output_dir and download_images:
-            out_path = Path(output_dir)
-            out_path.mkdir(parents=True, exist_ok=True)
-
-        documents: list[Document] = []
-        for part in iterator:
-            # Récupérer les transcriptions
-            transcriptions = self.get_transcriptions(doc_pk, part.pk)
-            gt_text = ""
-            for t in transcriptions:
-                layer_name = t.get("transcription", {}).get("name", "") if isinstance(t.get("transcription"), dict) else t.get("name", "")
-                if layer_name == transcription_layer or not transcription_layer:
-                    # Le contenu est dans "content" ou dans les lignes
-                    lines = t.get("lines", []) or []
-                    if lines:
-                        gt_text = "\n".join(
-                            line.get("content", "") or ""
-                            for line in lines
-                            if line.get("content")
-                        )
-                    else:
-                        gt_text = t.get("content", "") or ""
-                    break
-
-            # Image
-            image_path = part.image_url or f"escriptorium://doc{doc_pk}/part{part.pk}"
-            if out_path and part.image_url and download_images:
-                ext = Path(urllib.parse.urlparse(part.image_url).path).suffix or ".jpg"
-                local_img = out_path / f"part_{part.pk:05d}{ext}"
-                try:
-                    urllib.request.urlretrieve(part.image_url, local_img)
-                    image_path = str(local_img)
-                except Exception as exc:
-                    logger.warning("Impossible de télécharger l'image %s: %s", part.image_url, exc)
-
-                # Sauvegarder la GT
-                gt_path = out_path / f"part_{part.pk:05d}.gt.txt"
-                gt_path.write_text(gt_text, encoding="utf-8")
-
-            documents.append(Document(
-                doc_id=f"part_{part.pk:05d}",
-                image_path=image_path,
-                ground_truth=gt_text,
-                metadata={
-                    "source": "escriptorium",
-                    "doc_pk": doc_pk,
-                    "part_pk": part.pk,
-                    "part_title": part.title,
-                    "transcription_layer": transcription_layer,
-                },
-            ))
-
-        return Corpus(
-            name=doc_name,
-            source=f"{self.base_url}/document/{doc_pk}/",
-            documents=documents,
-            metadata={
-                "escriptorium_url": self.base_url,
-                "doc_pk": doc_pk,
-                "transcription_layer": transcription_layer,
-            },
-        )
-
-    def export_benchmark_as_layer(
-        self,
-        benchmark_result: "BenchmarkResult",
-        doc_pk: int,
-        engine_name: str,
-        layer_name: Optional[str] = None,
-        part_mapping: Optional[dict[str, int]] = None,
-    ) -> int:
-        """Exporte les résultats Picarones comme couche OCR dans eScriptorium.
-
-        Parameters
-        ----------
-        benchmark_result:
-            Résultats du benchmark Picarones.
-        doc_pk:
-            PK du document cible dans eScriptorium.
-        engine_name:
-            Nom du moteur dont on exporte les transcriptions.
-        layer_name:
-            Nom de la couche à créer (défaut : ``"picarones_{engine_name}"``).
-        part_mapping:
-            Correspondance ``doc_id → part_pk`` eScriptorium. Si None,
-            la correspondance est inférée depuis les métadonnées des documents.
-
-        Returns
-        -------
-        int
-            Nombre de pages exportées avec succès.
-        """
-        if layer_name is None:
-            layer_name = f"picarones_{engine_name}"
-
-        # Trouver le rapport du moteur
-        engine_report = None
-        for report in benchmark_result.engine_reports:
-            if report.engine_name == engine_name:
-                engine_report = report
-                break
-        if engine_report is None:
-            raise ValueError(f"Moteur '{engine_name}' introuvable dans les résultats.")
-
-        exported = 0
-        for doc_result in engine_report.document_results:
-            if doc_result.engine_error:
-                continue
-
-            # Déterminer le part_pk
-            part_pk: Optional[int] = None
-            if part_mapping and doc_result.doc_id in part_mapping:
-                part_pk = part_mapping[doc_result.doc_id]
-            else:
-                # Essayer d'extraire depuis doc_id (ex: "part_00042")
-                try:
-                    part_pk = int(doc_result.doc_id.replace("part_", "").lstrip("0") or "0")
-                except ValueError:
-                    logger.warning("Impossible de déterminer part_pk pour %s", doc_result.doc_id)
-                    continue
-
-            try:
-                self._post(
-                    f"documents/{doc_pk}/parts/{part_pk}/transcriptions/",
-                    {
-                        "name": layer_name,
-                        "content": doc_result.hypothesis,
-                        "source": "picarones",
-                    },
-                )
-                exported += 1
-                logger.debug("Exporté part %d → couche '%s'", part_pk, layer_name)
-            except RuntimeError as exc:
-                logger.warning("Erreur export part %d: %s", part_pk, exc)
-
-        return exported
-
-
-# ---------------------------------------------------------------------------
-# Interface de niveau module
-# ---------------------------------------------------------------------------
-
-def connect_escriptorium(
-    base_url: str,
-    token: str,
-    timeout: int = 30,
-) -> EScriptoriumClient:
-    """Crée et retourne un client eScriptorium authentifié.
-
-    Parameters
-    ----------
-    base_url:
-        URL de l'instance eScriptorium.
-    token:
-        Token API.
-    timeout:
-        Timeout HTTP.
-
-    Returns
-    -------
-    EScriptoriumClient
+from picarones.extras.importers.escriptorium import *  # noqa: F401, F403
 
-    Raises
-    ------
-    RuntimeError
-        Si la connexion échoue (URL invalide, token incorrect, serveur inaccessible).
-    """
-    client = EScriptoriumClient(base_url, token, timeout)
-    if not client.test_connection():
-        raise RuntimeError(
-            f"Impossible de se connecter à {base_url}. "
-            "Vérifiez l'URL et le token API."
-        )
-    return client
+import picarones.extras.importers.escriptorium as _module
+__all__ = getattr(_module, "__all__", [
+    name for name in dir(_module) if not name.startswith("_")
+])

picarones/importers/gallica.py

@@ -1,553 +1,17 @@
-"""Import de corpus depuis Gallica (BnF) via l'API SRU et IIIF.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.extras.importers.gallica`.
 
-Fonctionnement
---------------
-1. Recherche dans Gallica par cote (ark), titre, auteur ou date via l'API SRU BnF
-2. Récupération des images via l'API IIIF Gallica
-3. Récupération de l'OCR Gallica existant (texte brut ou ALTO) comme concurrent de référence
+Phase C du chantier de refonte en 3 cercles (architecture-cercles.md).
+Cet importeur est désormais en Cercle 3 (``extras/importers/``). L'alias
+ici permet aux imports historiques (``from picarones.importers.gallica
+import ...``) de continuer à fonctionner.
 
-API utilisées
--------------
-- SRU BnF : https://gallica.bnf.fr/SRU?operation=searchRetrieve&query=...
-- IIIF Gallica : https://gallica.bnf.fr/ark:/12148/{ark}/manifest.json
-- OCR texte brut : https://gallica.bnf.fr/ark:/12148/{ark}/f{n}.texteBrut
-- Métadonnées OAI-PMH : https://gallica.bnf.fr/services/OAIRecord?ark={ark}
-
-Usage
------
->>> from picarones.importers.gallica import GallicaClient
->>> client = GallicaClient()
->>> results = client.search(title="Froissart", date_from=1380, date_to=1420, max_results=10)
->>> corpus = client.import_document(results[0].ark, pages="1-5", include_gallica_ocr=True)
+Voir :doc:`docs/architecture-cercles.md` et l'extra
+``picarones[importers]`` du ``pyproject.toml``.
 """
 
-from __future__ import annotations
-
-import logging
-import re
-import time
-import urllib.error
-import urllib.parse
-import urllib.request
-import xml.etree.ElementTree as ET
-from dataclasses import dataclass
-from typing import Optional
-
-from picarones.core.corpus import Corpus
-
-logger = logging.getLogger(__name__)
-
-# Namespaces SRU/OAI
-_NS_SRU = "http://www.loc.gov/zing/srw/"
-_NS_DC = "http://purl.org/dc/elements/1.1/"
-_NS_OAI = "http://www.openarchives.org/OAI/2.0/"
-
-_GALLICA_BASE = "https://gallica.bnf.fr"
-_SRU_URL = f"{_GALLICA_BASE}/SRU"
-_IIIF_MANIFEST_TPL = f"{_GALLICA_BASE}/ark:/{{ark}}/manifest.json"
-_OCR_BRUT_TPL = f"{_GALLICA_BASE}/ark:/{{ark}}/f{{page}}.texteBrut"
-
-
-# ---------------------------------------------------------------------------
-# Structures de données
-# ---------------------------------------------------------------------------
-
-@dataclass
-class GallicaRecord:
-    """Un résultat de recherche Gallica."""
-    ark: str
-    """Identifiant ARK sans préfixe (ex: ``'12148/btv1b8453561w'``)."""
-    title: str
-    creator: str = ""
-    date: str = ""
-    description: str = ""
-    type_doc: str = ""
-    language: str = ""
-    rights: str = ""
-    has_ocr: bool = False
-    """True si Gallica fournit un OCR pour ce document."""
-
-    @property
-    def url(self) -> str:
-        return f"{_GALLICA_BASE}/ark:/12148/{self.ark}"
-
-    @property
-    def manifest_url(self) -> str:
-        return f"{_GALLICA_BASE}/ark:/12148/{self.ark}/manifest.json"
-
-    def as_dict(self) -> dict:
-        return {
-            "ark": self.ark,
-            "title": self.title,
-            "creator": self.creator,
-            "date": self.date,
-            "description": self.description,
-            "type_doc": self.type_doc,
-            "language": self.language,
-            "has_ocr": self.has_ocr,
-            "url": self.url,
-            "manifest_url": self.manifest_url,
-        }
-
-
-# ---------------------------------------------------------------------------
-# Client Gallica
-# ---------------------------------------------------------------------------
-
-class GallicaClient:
-    """Client pour les APIs Gallica (SRU, IIIF, OCR texte brut).
-
-    Parameters
-    ----------
-    timeout:
-        Timeout HTTP en secondes.
-    delay_between_requests:
-        Délai en secondes entre chaque requête (pour respecter les conditions
-        d'utilisation Gallica).
-
-    Examples
-    --------
-    >>> client = GallicaClient()
-    >>> results = client.search(author="Froissart", max_results=5)
-    >>> for r in results:
-    ...     print(r.title, r.date)
-    >>> corpus = client.import_document(results[0].ark, pages="1-3")
-    """
-
-    def __init__(
-        self,
-        timeout: int = 30,
-        delay_between_requests: float = 0.5,
-    ) -> None:
-        self.timeout = timeout
-        self.delay = delay_between_requests
-
-    # Chantier 4 (post-Sprint 97) — fusion Gallica → IIIF :
-    # ``_validate_url`` et le fetch HTTP sont désormais factorisés
-    # dans :mod:`picarones.importers._http`. Avant ce chantier ces
-    # 30 lignes étaient dupliquées avec :mod:`iiif`. Le polite
-    # ``delay_between_requests`` reste ici (spécifique à la BnF).
-
-    @staticmethod
-    def _validate_url(url: str) -> None:
-        """Délègue à :func:`picarones.importers._http.validate_http_url`."""
-        from picarones.importers._http import validate_http_url
-        validate_http_url(url)
-
-    def _fetch_url(self, url: str) -> bytes:
-        """Télécharge le contenu d'une URL avec respect du polite delay BnF.
-
-        Délègue à :func:`picarones.importers._http.download_url` puis
-        applique ``self.delay`` (par défaut 0.5 s) entre les requêtes
-        pour respecter les conditions d'utilisation Gallica.
-        """
-        from picarones.importers._http import download_url
-        try:
-            return download_url(
-                url,
-                retries=1,
-                timeout=self.timeout,
-                user_agent="Picarones/1.0 (research tool)",
-            )
-        except RuntimeError as exc:
-            # Le helper retourne ``RuntimeError`` après retries épuisés.
-            # On re-emballe pour conserver le format de message historique
-            # attendu par les tests Gallica (« HTTP 404 sur ... »).
-            raise RuntimeError(str(exc)) from exc
-        finally:
-            if self.delay > 0:
-                time.sleep(self.delay)
-
-    def _build_sru_query(
-        self,
-        ark: Optional[str] = None,
-        title: Optional[str] = None,
-        author: Optional[str] = None,
-        date_from: Optional[int] = None,
-        date_to: Optional[int] = None,
-        doc_type: Optional[str] = None,
-        language: Optional[str] = None,
-    ) -> str:
-        """Construit une requête CQL pour l'API SRU BnF."""
-        clauses: list[str] = []
-
-        if ark:
-            # Recherche par identifiant ARK
-            clauses.append(f'dc.identifier any "{ark}"')
-        if title:
-            clauses.append(f'dc.title all "{title}"')
-        if author:
-            clauses.append(f'dc.creator all "{author}"')
-        if date_from and date_to:
-            clauses.append(f'dc.date >= "{date_from}" and dc.date <= "{date_to}"')
-        elif date_from:
-            clauses.append(f'dc.date >= "{date_from}"')
-        elif date_to:
-            clauses.append(f'dc.date <= "{date_to}"')
-        if doc_type:
-            clauses.append(f'dc.type all "{doc_type}"')
-        if language:
-            clauses.append(f'dc.language all "{language}"')
-
-        if not clauses:
-            return 'gallica all "document"'
-        return " and ".join(clauses)
-
-    def search(
-        self,
-        ark: Optional[str] = None,
-        title: Optional[str] = None,
-        author: Optional[str] = None,
-        date_from: Optional[int] = None,
-        date_to: Optional[int] = None,
-        doc_type: Optional[str] = None,
-        language: Optional[str] = None,
-        max_results: int = 20,
-    ) -> list[GallicaRecord]:
-        """Recherche dans Gallica via l'API SRU BnF.
-
-        Parameters
-        ----------
-        ark:
-            Identifiant ARK (ex : ``'12148/btv1b8453561w'``).
-        title:
-            Mots-clés dans le titre.
-        author:
-            Mots-clés dans l'auteur/créateur.
-        date_from:
-            Borne inférieure de date (année).
-        date_to:
-            Borne supérieure de date (année).
-        doc_type:
-            Type de document (``'monographie'``, ``'périodique'``, ``'manuscrit'``…).
-        language:
-            Code langue ISO 639 (``'fre'``, ``'lat'``, ``'ger'``…).
-        max_results:
-            Nombre maximum de résultats à retourner.
-
-        Returns
-        -------
-        list[GallicaRecord]
-            Liste des documents trouvés.
-        """
-        query = self._build_sru_query(
-            ark=ark,
-            title=title,
-            author=author,
-            date_from=date_from,
-            date_to=date_to,
-            doc_type=doc_type,
-            language=language,
-        )
-
-        params = urllib.parse.urlencode({
-            "operation": "searchRetrieve",
-            "version": "1.2",
-            "query": query,
-            "maximumRecords": min(max_results, 50),
-            "startRecord": 1,
-            "recordSchema": "unimarcXchange",
-        })
-        url = f"{_SRU_URL}?{params}"
-
-        try:
-            raw = self._fetch_url(url)
-        except RuntimeError as exc:
-            logger.error("Erreur recherche SRU Gallica: %s", exc)
-            return []
-
-        return self._parse_sru_response(raw, max_results)
-
-    def _parse_sru_response(self, xml_bytes: bytes, max_results: int) -> list[GallicaRecord]:
-        """Parse la réponse SRU XML de Gallica."""
-        records: list[GallicaRecord] = []
-        try:
-            root = ET.fromstring(xml_bytes)
-        except ET.ParseError as exc:
-            logger.error("Impossible de parser la réponse SRU: %s", exc)
-            return records
-
-        # Les enregistrements sont dans srw:records/srw:record/srw:recordData
-        for rec_elem in root.iter():
-            if rec_elem.tag.endswith("}record") or rec_elem.tag == "record":
-                record = self._parse_record_element(rec_elem)
-                if record:
-                    records.append(record)
-                if len(records) >= max_results:
-                    break
-
-        return records
-
-    def _parse_record_element(self, elem: ET.Element) -> Optional[GallicaRecord]:
-        """Extrait les métadonnées d'un enregistrement SRU."""
-        # Chercher les champs Dublin Core dans l'enregistrement
-        def find_text(tag_suffix: str) -> str:
-            for child in elem.iter():
-                if child.tag.endswith(tag_suffix) and child.text:
-                    return child.text.strip()
-            return ""
-
-        def find_all_text(tag_suffix: str) -> list[str]:
-            return [
-                child.text.strip()
-                for child in elem.iter()
-                if child.tag.endswith(tag_suffix) and child.text
-            ]
-
-        # Chercher l'ARK dans l'identifiant
-        identifiers = find_all_text("identifier")
-        ark = ""
-        for ident in identifiers:
-            # Format typique : "https://gallica.bnf.fr/ark:/12148/btv1b8453561w"
-            m = re.search(r"ark:/(\d+/\w+)", ident)
-            if m:
-                ark = m.group(1)
-                break
-
-        if not ark:
-            return None
-
-        title = find_text("title") or "Sans titre"
-        creator = find_text("creator")
-        date = find_text("date")
-
-        # Vérifier si OCR disponible (heuristique : type monographie/périodique généralement)
-        doc_types = find_all_text("type")
-        has_ocr = any(
-            t.lower() in ("monographie", "fascicule", "texte", "text")
-            for t in doc_types
-        )
-
-        return GallicaRecord(
-            ark=ark,
-            title=title,
-            creator=creator,
-            date=date,
-            description=find_text("description"),
-            type_doc=", ".join(doc_types),
-            language=find_text("language"),
-            has_ocr=has_ocr,
-        )
-
-    def get_ocr_text(self, ark: str, page: int) -> str:
-        """Récupère l'OCR Gallica d'une page spécifique (texte brut).
-
-        Parameters
-        ----------
-        ark:
-            Identifiant ARK (ex : ``'12148/btv1b8453561w'``).
-        page:
-            Numéro de page 1-based.
-
-        Returns
-        -------
-        str
-            Texte OCR Gallica pour cette page (peut être vide si non disponible).
-        """
-        url = _OCR_BRUT_TPL.format(ark=ark, page=page)
-        try:
-            raw = self._fetch_url(url)
-            text = raw.decode("utf-8", errors="replace").strip()
-            # Gallica retourne parfois du HTML pour les pages sans OCR
-            if text.startswith("<!") or "<html" in text[:100].lower():
-                return ""
-            return text
-        except RuntimeError as exc:
-            logger.debug("OCR non disponible pour %s f%d: %s", ark, page, exc)
-            return ""
-
-    def import_document(
-        self,
-        ark: str,
-        pages: str = "all",
-        output_dir: Optional[str] = None,
-        include_gallica_ocr: bool = True,
-        max_resolution: int = 0,
-        show_progress: bool = True,
-    ) -> Corpus:
-        """Importe un document Gallica comme corpus Picarones.
-
-        Utilise le manifeste IIIF Gallica pour lister les pages et télécharger
-        les images. L'OCR Gallica est optionnellement récupéré comme GT ou comme
-        transcription de référence.
-
-        Parameters
-        ----------
-        ark:
-            Identifiant ARK (ex : ``'12148/btv1b8453561w'``).
-        pages:
-            Sélecteur de pages (``'all'``, ``'1-10'``, ``'1,3,5'``…).
-        output_dir:
-            Dossier local pour stocker images et GT.
-        include_gallica_ocr:
-            Si True, récupère l'OCR Gallica comme texte de référence.
-        max_resolution:
-            Largeur maximale des images téléchargées (0 = maximum disponible).
-        show_progress:
-            Affiche une barre de progression.
-
-        Returns
-        -------
-        Corpus
-            Corpus avec images et OCR Gallica comme GT (si disponible).
-        """
-        from picarones.importers.iiif import IIIFImporter
-
-        manifest_url = f"{_GALLICA_BASE}/ark:/12148/{ark}/manifest.json"
-        logger.info("Import Gallica ARK %s via IIIF : %s", ark, manifest_url)
-
-        # Utiliser l'importeur IIIF existant pour les images
-        importer = IIIFImporter(manifest_url, max_resolution=max_resolution)
-        importer.load()
-
-        corpus = importer.import_corpus(
-            pages=pages,
-            output_dir=output_dir or f"./corpus_gallica_{ark.split('/')[-1]}/",
-            show_progress=show_progress,
-        )
-
-        # Enrichir avec l'OCR Gallica si demandé
-        if include_gallica_ocr:
-            selected_indices = importer.list_canvases(pages)
-            for i, doc in enumerate(corpus.documents):
-                page_num = selected_indices[i] + 1 if i < len(selected_indices) else i + 1
-                gallica_ocr = self.get_ocr_text(ark, page_num)
-                if gallica_ocr:
-                    doc.metadata["gallica_ocr"] = gallica_ocr
-                    # Si pas de GT manuscrite, utiliser l'OCR Gallica comme référence
-                    if not doc.ground_truth.strip():
-                        doc.ground_truth = gallica_ocr
-                        doc.metadata["gt_source"] = "gallica_ocr"
-
-        # Ajouter métadonnées Gallica
-        corpus.metadata.update({
-            "source": "gallica",
-            "ark": ark,
-            "manifest_url": manifest_url,
-            "gallica_url": f"{_GALLICA_BASE}/ark:/12148/{ark}",
-            "include_gallica_ocr": include_gallica_ocr,
-        })
-
-        return corpus
-
-    def get_metadata(self, ark: str) -> dict:
-        """Récupère les métadonnées OAI-PMH d'un document Gallica.
-
-        Parameters
-        ----------
-        ark:
-            Identifiant ARK.
-
-        Returns
-        -------
-        dict
-            Métadonnées Dublin Core du document.
-        """
-        url = f"{_GALLICA_BASE}/services/OAIRecord?ark=ark:/12148/{ark}"
-        try:
-            raw = self._fetch_url(url)
-            root = ET.fromstring(raw)
-        except (RuntimeError, ET.ParseError) as exc:
-            logger.error("Erreur métadonnées OAI %s: %s", ark, exc)
-            return {"ark": ark}
-
-        def find_text(tag_suffix: str) -> str:
-            for elem in root.iter():
-                if elem.tag.endswith(tag_suffix) and elem.text:
-                    return elem.text.strip()
-            return ""
-
-        return {
-            "ark": ark,
-            "title": find_text("title"),
-            "creator": find_text("creator"),
-            "date": find_text("date"),
-            "description": find_text("description"),
-            "subject": find_text("subject"),
-            "language": find_text("language"),
-            "type": find_text("type"),
-            "format": find_text("format"),
-            "source": find_text("source"),
-            "url": f"{_GALLICA_BASE}/ark:/12148/{ark}",
-        }
-
-
-# ---------------------------------------------------------------------------
-# Fonctions de commodité
-# ---------------------------------------------------------------------------
-
-def search_gallica(
-    title: Optional[str] = None,
-    author: Optional[str] = None,
-    ark: Optional[str] = None,
-    date_from: Optional[int] = None,
-    date_to: Optional[int] = None,
-    max_results: int = 20,
-) -> list[GallicaRecord]:
-    """Recherche rapide dans Gallica.
-
-    Crée un client temporaire et effectue une recherche.
-
-    Parameters
-    ----------
-    title, author, ark, date_from, date_to:
-        Critères de recherche.
-    max_results:
-        Nombre maximum de résultats.
-
-    Returns
-    -------
-    list[GallicaRecord]
-
-    Examples
-    --------
-    >>> results = search_gallica(title="Froissart", date_from=1380, date_to=1430)
-    >>> for r in results[:3]:
-    ...     print(r.title, r.ark)
-    """
-    client = GallicaClient()
-    return client.search(
-        ark=ark,
-        title=title,
-        author=author,
-        date_from=date_from,
-        date_to=date_to,
-        max_results=max_results,
-    )
-
-
-def import_gallica_document(
-    ark: str,
-    pages: str = "all",
-    output_dir: Optional[str] = None,
-    include_gallica_ocr: bool = True,
-) -> Corpus:
-    """Importe un document Gallica en une ligne.
-
-    Parameters
-    ----------
-    ark:
-        Identifiant ARK (``'12148/btv1b8453561w'`` ou URL complète).
-    pages:
-        Sélecteur de pages (``'all'``, ``'1-10'``…).
-    output_dir:
-        Dossier de sortie.
-    include_gallica_ocr:
-        Inclure l'OCR Gallica comme GT.
-
-    Returns
-    -------
-    Corpus
-    """
-    # Normaliser l'ARK (extraire depuis URL complète si besoin)
-    m = re.search(r"ark:/(\d+/\w+)", ark)
-    if m:
-        ark = m.group(1)
+from picarones.extras.importers.gallica import *  # noqa: F401, F403
 
-    client = GallicaClient()
-    return client.import_document(
-        ark=ark,
-        pages=pages,
-        output_dir=output_dir,
-        include_gallica_ocr=include_gallica_ocr,
-    )
+import picarones.extras.importers.gallica as _module
+__all__ = getattr(_module, "__all__", [
+    name for name in dir(_module) if not name.startswith("_")
+])

picarones/importers/htr_united.py

@@ -1,455 +1,17 @@
-"""Import depuis le catalogue HTR-United.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.extras.importers.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.
+Phase C du chantier de refonte en 3 cercles (architecture-cercles.md).
+Cet importeur est désormais en Cercle 3 (``extras/importers/``). L'alias
+ici permet aux imports historiques (``from picarones.importers.htr_united
+import ...``) de continuer à fonctionner.
 
-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/")
+Voir :doc:`docs/architecture-cercles.md` et l'extra
+``picarones[importers]`` du ``pyproject.toml``.
 """
 
-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:
-        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:
-        pass
-    return [HTRUnitedEntry.from_dict(d) for d in _DEMO_CATALOGUE]
-
+from picarones.extras.importers.htr_united import *  # noqa: F401, F403
 
-def _iso_now() -> str:
-    from datetime import datetime, timezone
-    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+import picarones.extras.importers.htr_united as _module
+__all__ = getattr(_module, "__all__", [
+    name for name in dir(_module) if not name.startswith("_")
+])

picarones/importers/huggingface.py

@@ -1,427 +1,17 @@
-"""Import de datasets OCR/HTR depuis HuggingFace Hub.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.extras.importers.huggingface`.
 
-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
+Phase C du chantier de refonte en 3 cercles (architecture-cercles.md).
+Cet importeur est désormais en Cercle 3 (``extras/importers/``). L'alias
+ici permet aux imports historiques (``from picarones.importers.huggingface
+import ...``) de continuer à fonctionner.
 
-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/")
+Voir :doc:`docs/architecture-cercles.md` et l'extra
+``picarones[importers]`` du ``pyproject.toml``.
 """
 
-from __future__ import annotations
-
-import json
-import os
-import urllib.error
-import urllib.parse
-import urllib.request
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Optional
-
-# ---------------------------------------------------------------------------
-# 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:
-            pass
-
-        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:
-                    pass
-
-            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
-
+from picarones.extras.importers.huggingface import *  # noqa: F401, F403
 
-_patch_dataset_replace_source()
+import picarones.extras.importers.huggingface as _module
+__all__ = getattr(_module, "__all__", [
+    name for name in dir(_module) if not name.startswith("_")
+])

picarones/importers/iiif.py

@@ -1,565 +1,17 @@
-"""Import de corpus depuis des manifestes IIIF v2 et v3.
+"""Alias rétrocompat — module déplacé dans :mod:`picarones.extras.importers.iiif`.
 
-Fonctionnement
---------------
-1. Téléchargement et parsing du manifeste JSON (v2 ou v3 auto-détecté)
-2. Extraction de la liste des canvases (pages) avec leurs URL d'image
-3. Sélection optionnelle d'un sous-ensemble de pages (ex : ``--pages 1-10``)
-4. Téléchargement des images dans un dossier local
-5. Création de fichiers GT vides (``.gt.txt``) à remplir manuellement,
-   OU chargement des annotations de transcription si présentes dans le manifeste
-6. Construction et retour d'un objet ``Corpus``
+Phase C du chantier de refonte en 3 cercles (architecture-cercles.md).
+Cet importeur est désormais en Cercle 3 (``extras/importers/``). L'alias
+ici permet aux imports historiques (``from picarones.importers.iiif
+import ...``) de continuer à fonctionner.
 
-Compatibilité
--------------
-- IIIF Image API v2 et v3
-- Manifestes Presentation API v2 et v3
-- Instances : Gallica (BnF), Bodleian, British Library, BSB, e-codices,
-  Europeana, et tout entrepôt IIIF-compliant
-
-Utilisation
------------
->>> from picarones.importers.iiif import IIIFImporter
->>> importer = IIIFImporter("https://gallica.bnf.fr/ark:/12148/xxx/manifest.json")
->>> corpus = importer.import_corpus(pages="1-10", output_dir="./corpus/")
->>> print(f"{len(corpus)} documents téléchargés")
-
-Ou via la fonction de commodité :
->>> from picarones.importers.iiif import import_iiif_manifest
->>> corpus = import_iiif_manifest("https://...", pages="1-5", output_dir="./corpus/")
+Voir :doc:`docs/architecture-cercles.md` et l'extra
+``picarones[importers]`` du ``pyproject.toml``.
 """
 
-from __future__ import annotations
-
-import json
-import logging
-import re
-import time
-import urllib.error
-import urllib.request
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Iterator, Optional
-
-from picarones.core.corpus import Corpus, Document
-
-logger = logging.getLogger(__name__)
-
-
-# ---------------------------------------------------------------------------
-# Parsing du sélecteur de pages
-# ---------------------------------------------------------------------------
-
-def parse_page_selector(pages: str, total: int) -> list[int]:
-    """Parse un sélecteur de pages en liste d'indices 0-based.
-
-    Formats acceptés :
-    - ``"1-10"``        → pages 1 à 10 (1-based)
-    - ``"1,3,5"``       → pages 1, 3 et 5
-    - ``"1-5,10,15-20"`` → combinaison
-    - ``"all"`` / ``""`` → toutes les pages
-
-    Parameters
-    ----------
-    pages:
-        Sélecteur de pages en chaîne de caractères.
-    total:
-        Nombre total de pages dans le manifeste.
-
-    Returns
-    -------
-    list[int]
-        Indices 0-based des pages sélectionnées, triés et dédoublonnés.
-
-    Raises
-    ------
-    ValueError
-        Si la syntaxe est invalide ou les numéros hors bornes.
-    """
-    if not pages or pages.strip().lower() == "all":
-        return list(range(total))
-
-    indices: set[int] = set()
-    for part in pages.split(","):
-        part = part.strip()
-        if "-" in part:
-            m = re.fullmatch(r"(\d+)-(\d+)", part)
-            if not m:
-                raise ValueError(f"Sélecteur de pages invalide : '{part}'")
-            start, end = int(m.group(1)), int(m.group(2))
-            if start < 1 or end > total or start > end:
-                raise ValueError(
-                    f"Plage {start}-{end} hors bornes (1–{total})"
-                )
-            indices.update(range(start - 1, end))
-        else:
-            n = int(part)
-            if n < 1 or n > total:
-                raise ValueError(f"Page {n} hors bornes (1–{total})")
-            indices.add(n - 1)
-    return sorted(indices)
-
-
-# ---------------------------------------------------------------------------
-# Données d'un canvas IIIF
-# ---------------------------------------------------------------------------
-
-@dataclass
-class IIIFCanvas:
-    """Représente un canvas (page) dans un manifeste IIIF."""
-
-    index: int          # position 0-based dans le manifeste
-    label: str          # étiquette lisible (ex : "f. 1r", "Page 1")
-    image_url: str      # URL de l'image pleine résolution
-    width: Optional[int] = None
-    height: Optional[int] = None
-    transcription: Optional[str] = None  # texte GT si annoté dans le manifeste
-
-
-# ---------------------------------------------------------------------------
-# Parseur de manifeste IIIF
-# ---------------------------------------------------------------------------
-
-class IIIFManifestParser:
-    """Parse un manifeste IIIF Presentation API v2 ou v3."""
-
-    def __init__(self, manifest: dict) -> None:
-        self._manifest = manifest
-        self._version = self._detect_version()
-
-    def _detect_version(self) -> int:
-        """Détecte la version du manifeste (2 ou 3)."""
-        context = self._manifest.get("@context", "")
-        if isinstance(context, list):
-            context = " ".join(context)
-        if "presentation/3" in context or self._manifest.get("type") == "Manifest":
-            return 3
-        return 2
-
-    @property
-    def version(self) -> int:
-        return self._version
-
-    @property
-    def label(self) -> str:
-        """Titre du manifeste."""
-        raw = self._manifest.get("label", "")
-        return _extract_label(raw)
-
-    @property
-    def attribution(self) -> str:
-        raw = self._manifest.get("attribution", self._manifest.get("requiredStatement", ""))
-        return _extract_label(raw)
-
-    def canvases(self) -> list[IIIFCanvas]:
-        """Retourne la liste des canvases du manifeste."""
-        if self._version == 3:
-            return self._parse_v3_canvases()
-        return self._parse_v2_canvases()
-
-    def _parse_v2_canvases(self) -> list[IIIFCanvas]:
-        canvases: list[IIIFCanvas] = []
-        sequences = self._manifest.get("sequences", [])
-        if not sequences:
-            return canvases
-        raw_canvases = sequences[0].get("canvases", [])
-        for i, canvas in enumerate(raw_canvases):
-            label = _extract_label(canvas.get("label", f"canvas_{i+1}"))
-            # Image principale : images[0].resource.@id ou service
-            images = canvas.get("images", [])
-            image_url = ""
-            if images:
-                resource = images[0].get("resource", {})
-                image_url = _best_image_url_v2(resource, canvas)
-
-            # Annotations de transcription (OA annotations)
-            transcription = _extract_v2_transcription(canvas)
-
-            canvases.append(IIIFCanvas(
-                index=i,
-                label=label,
-                image_url=image_url,
-                width=canvas.get("width"),
-                height=canvas.get("height"),
-                transcription=transcription,
-            ))
-        return canvases
-
-    def _parse_v3_canvases(self) -> list[IIIFCanvas]:
-        canvases: list[IIIFCanvas] = []
-        items = self._manifest.get("items", [])
-        for i, canvas in enumerate(items):
-            label = _extract_label(canvas.get("label", f"canvas_{i+1}"))
-            image_url = _best_image_url_v3(canvas)
-            transcription = _extract_v3_transcription(canvas)
-            canvases.append(IIIFCanvas(
-                index=i,
-                label=label,
-                image_url=image_url,
-                width=canvas.get("width"),
-                height=canvas.get("height"),
-                transcription=transcription,
-            ))
-        return canvases
-
-
-# ---------------------------------------------------------------------------
-# Helpers extraction URL et label
-# ---------------------------------------------------------------------------
-
-def _extract_label(raw: object) -> str:
-    """Extrait une chaîne lisible depuis les différents formats de label IIIF."""
-    if isinstance(raw, str):
-        return raw
-    if isinstance(raw, list) and raw:
-        return _extract_label(raw[0])
-    if isinstance(raw, dict):
-        # IIIF v3 : {"fr": ["titre"], "en": ["title"]}
-        for lang in ("fr", "en", "none", "@value"):
-            val = raw.get(lang, "")
-            if val:
-                if isinstance(val, list):
-                    return val[0] if val else ""
-                return str(val)
-        # Fallback: première valeur
-        for v in raw.values():
-            return _extract_label(v)
-    return str(raw) if raw else ""
-
-
-def _best_image_url_v2(resource: dict, canvas: dict) -> str:
-    """Construit l'URL d'image optimale depuis une ressource IIIF v2."""
-    # 1. URL directe de la ressource
-    direct = resource.get("@id", "")
-    if direct and not direct.endswith("/info.json"):
-        return direct
-
-    # 2. Via le service IIIF Image API
-    service = resource.get("service", {})
-    if isinstance(service, list) and service:
-        service = service[0]
-    service_id = service.get("@id", service.get("id", ""))
-    if service_id:
-        return f"{service_id.rstrip('/')}/full/max/0/default.jpg"
-
-    return direct
-
-
-def _best_image_url_v3(canvas: dict) -> str:
-    """Extrait l'URL d'image depuis un canvas IIIF v3."""
-    items = canvas.get("items", [])
-    for annotation_page in items:
-        for annotation in annotation_page.get("items", []):
-            body = annotation.get("body", {})
-            if isinstance(body, list):
-                body = body[0] if body else {}
-            # URL directe
-            url = body.get("id", body.get("@id", ""))
-            if url and body.get("type", "") == "Image":
-                return url
-            # Via service IIIF Image API
-            service = body.get("service", [])
-            if isinstance(service, dict):
-                service = [service]
-            for svc in service:
-                svc_id = svc.get("id", svc.get("@id", ""))
-                if svc_id:
-                    return f"{svc_id.rstrip('/')}/full/max/0/default.jpg"
-            if url:
-                return url
-    return ""
-
-
-def _extract_v2_transcription(canvas: dict) -> Optional[str]:
-    """Tente d'extraire le texte GT depuis les annotations OA d'un canvas v2."""
-    other_content = canvas.get("otherContent", [])
-    for oc in other_content:
-        if not isinstance(oc, dict):
-            continue
-        motivation = oc.get("motivation", "")
-        if "transcrib" in motivation.lower() or "supplementing" in motivation.lower():
-            resources = oc.get("resources", [])
-            texts = []
-            for res in resources:
-                body = res.get("resource", {})
-                if body.get("@type") == "cnt:ContentAsText":
-                    texts.append(body.get("chars", ""))
-            if texts:
-                return "\n".join(texts)
-    return None
-
-
-def _extract_v3_transcription(canvas: dict) -> Optional[str]:
-    """Tente d'extraire le texte GT depuis les annotations d'un canvas v3."""
-    annotations = canvas.get("annotations", [])
-    for ann_page in annotations:
-        items = ann_page.get("items", [])
-        for ann in items:
-            motivation = ann.get("motivation", "")
-            if "transcrib" in motivation.lower() or "supplementing" in motivation.lower():
-                body = ann.get("body", {})
-                if isinstance(body, dict) and body.get("type") == "TextualBody":
-                    return body.get("value", "")
-    return None
-
-
-# ---------------------------------------------------------------------------
-# Téléchargement avec retry
-# ---------------------------------------------------------------------------
-
-# Chantier 4 (post-Sprint 97) — helpers HTTP factorisés dans
-# :mod:`picarones.importers._http`. Ces noms restent disponibles
-# depuis ``iiif`` (rétrocompat des tests qui les importent
-# directement, ex. test_sprint4_normalization_iiif).
-from picarones.importers._http import download_url as _download_url
-from picarones.importers._http import validate_http_url as _validate_url
-
-
-def _fetch_manifest(url: str) -> dict:
-    """Télécharge et parse un manifeste IIIF JSON."""
-    data = _download_url(url)
-    try:
-        return json.loads(data.decode("utf-8"))
-    except json.JSONDecodeError as exc:
-        raise ValueError(f"Manifeste IIIF invalide (JSON mal formé) : {url}") from exc
-
-
-# ---------------------------------------------------------------------------
-# Importeur principal
-# ---------------------------------------------------------------------------
-
-class IIIFImporter:
-    """Importe un corpus depuis un manifeste IIIF.
-
-    Parameters
-    ----------
-    manifest_url:
-        URL du manifeste IIIF (Presentation API v2 ou v3).
-    max_resolution:
-        Résolution maximale des images téléchargées (largeur en pixels).
-        0 = résolution maximale disponible.
-    """
-
-    def __init__(
-        self,
-        manifest_url: str,
-        max_resolution: int = 0,
-    ) -> None:
-        self.manifest_url = manifest_url
-        self.max_resolution = max_resolution
-        self._manifest: Optional[dict] = None
-        self._parser: Optional[IIIFManifestParser] = None
-
-    def load(self) -> "IIIFImporter":
-        """Télécharge et parse le manifeste."""
-        logger.info("Téléchargement du manifeste IIIF : %s", self.manifest_url)
-        self._manifest = _fetch_manifest(self.manifest_url)
-        self._parser = IIIFManifestParser(self._manifest)
-        logger.info(
-            "Manifeste chargé — version IIIF %d — titre : %s — %d canvas",
-            self._parser.version,
-            self._parser.label,
-            len(self._parser.canvases()),
-        )
-        return self
-
-    @property
-    def parser(self) -> IIIFManifestParser:
-        if self._parser is None:
-            self.load()
-        return self._parser  # type: ignore[return-value]
-
-    def list_canvases(self, pages: str = "all") -> list[IIIFCanvas]:
-        """Retourne la liste des canvases sélectionnés."""
-        all_canvases = self.parser.canvases()
-        indices = parse_page_selector(pages, len(all_canvases))
-        return [all_canvases[i] for i in indices]
-
-    def import_corpus(
-        self,
-        pages: str = "all",
-        output_dir: Optional[str | Path] = None,
-        show_progress: bool = True,
-    ) -> Corpus:
-        """Télécharge les images et construit un corpus Picarones.
-
-        Si les canvases contiennent des annotations de transcription (GT),
-        elles sont automatiquement sauvegardées dans les fichiers ``.gt.txt``.
-        Sinon, des fichiers ``.gt.txt`` vides sont créés.
-
-        Parameters
-        ----------
-        pages:
-            Sélecteur de pages (ex : ``"1-10"``, ``"1,3,5"``).
-        output_dir:
-            Dossier de destination pour les images et les GT.
-            Si None, le corpus est retourné en mémoire sans écriture disque.
-        show_progress:
-            Affiche une barre de progression tqdm.
-
-        Returns
-        -------
-        Corpus
-            Corpus prêt à être utilisé dans ``run_benchmark``.
-        """
-        canvases = self.list_canvases(pages)
-        if not canvases:
-            raise ValueError("Aucun canvas sélectionné.")
-
-        out_dir: Optional[Path] = Path(output_dir) if output_dir else None
-        if out_dir:
-            out_dir.mkdir(parents=True, exist_ok=True)
-
-        # Nom du corpus depuis le titre du manifeste
-        corpus_name = self.parser.label or "iiif_corpus"
-
-        documents: list[Document] = []
-        iterator: Iterator[IIIFCanvas] = iter(canvases)
-
-        if show_progress:
-            try:
-                from tqdm import tqdm
-                iterator = tqdm(canvases, desc="Import IIIF", unit="page")
-            except ImportError:
-                pass
-
-        for canvas in iterator:
-            doc_id = f"{_slugify(canvas.label) or f'canvas_{canvas.index+1:04d}'}"
-
-            if not canvas.image_url:
-                logger.warning("Canvas %s : pas d'URL d'image — ignoré.", canvas.label)
-                continue
-
-            # Ajuster la résolution si max_resolution est défini
-            image_url = self._adjust_resolution(canvas.image_url, canvas.width)
-
-            # Téléchargement de l'image
-            try:
-                image_bytes = _download_url(image_url)
-            except RuntimeError as exc:
-                logger.error("Canvas %s : erreur téléchargement : %s", canvas.label, exc)
-                continue
-
-            # Déterminer l'extension de l'image
-            ext = _guess_extension(image_url)
-
-            if out_dir:
-                # Sauvegarde sur disque
-                image_path = out_dir / f"{doc_id}{ext}"
-                image_path.write_bytes(image_bytes)
-
-                gt_path = out_dir / f"{doc_id}.gt.txt"
-                gt_text = canvas.transcription or ""
-                gt_path.write_text(gt_text, encoding="utf-8")
-
-                documents.append(Document(
-                    image_path=image_path,
-                    ground_truth=gt_text,
-                    doc_id=doc_id,
-                    metadata={"iiif_label": canvas.label, "canvas_index": canvas.index},
-                ))
-            else:
-                # Corpus en mémoire (image stockée comme chemin temporaire virtuel)
-                import tempfile
-                tmp = tempfile.NamedTemporaryFile(suffix=ext, delete=False)
-                tmp.write(image_bytes)
-                tmp.close()
-                documents.append(Document(
-                    image_path=Path(tmp.name),
-                    ground_truth=canvas.transcription or "",
-                    doc_id=doc_id,
-                    metadata={"iiif_label": canvas.label, "canvas_index": canvas.index},
-                ))
-
-        if not documents:
-            raise ValueError("Aucun document importé depuis le manifeste IIIF.")
-
-        logger.info("Import IIIF terminé : %d documents.", len(documents))
-
-        return Corpus(
-            name=corpus_name,
-            documents=documents,
-            source_path=self.manifest_url,
-            metadata={
-                "iiif_manifest_url": self.manifest_url,
-                "iiif_version": self.parser.version,
-                "iiif_attribution": self.parser.attribution,
-                "pages_selected": pages,
-            },
-        )
-
-    def _adjust_resolution(self, image_url: str, canvas_width: Optional[int]) -> str:
-        """Ajuste l'URL IIIF Image API pour respecter max_resolution."""
-        if not self.max_resolution or not canvas_width:
-            return image_url
-        if canvas_width <= self.max_resolution:
-            return image_url
-        # Remplacer /full/max/ ou /full/full/ par /full/{w},/
-        url = re.sub(
-            r"/full/(max|full)/",
-            f"/full/{self.max_resolution},/",
-            image_url,
-        )
-        return url
-
-
-# ---------------------------------------------------------------------------
-# Helpers utilitaires
-# ---------------------------------------------------------------------------
-
-def _slugify(text: str) -> str:
-    """Convertit un label IIIF en identifiant de fichier sûr."""
-    text = re.sub(r"[^\w\s-]", "", text.strip())
-    text = re.sub(r"[\s_-]+", "_", text)
-    return text[:60]
-
-
-def _guess_extension(url: str) -> str:
-    """Détermine l'extension de l'image depuis l'URL."""
-    url_lower = url.lower().split("?")[0]
-    for ext in (".jpg", ".jpeg", ".png", ".tif", ".tiff", ".webp"):
-        if url_lower.endswith(ext):
-            return ext
-    # Par défaut pour les URLs IIIF Image API
-    if "/default." in url_lower or "/native." in url_lower:
-        return ".jpg"
-    return ".jpg"
-
-
-# ---------------------------------------------------------------------------
-# Fonction de commodité
-# ---------------------------------------------------------------------------
-
-def import_iiif_manifest(
-    manifest_url: str,
-    pages: str = "all",
-    output_dir: Optional[str | Path] = None,
-    max_resolution: int = 0,
-    show_progress: bool = True,
-) -> Corpus:
-    """Importe un corpus depuis un manifeste IIIF en une seule ligne.
-
-    Parameters
-    ----------
-    manifest_url:
-        URL du manifeste IIIF (v2 ou v3).
-    pages:
-        Sélecteur de pages (ex : ``"1-10"``, ``"1,3,5"``). ``"all"`` par défaut.
-    output_dir:
-        Dossier de destination. Si None, corpus en mémoire.
-    max_resolution:
-        Résolution maximale (px). 0 = pas de limite.
-    show_progress:
-        Affiche une barre de progression.
+from picarones.extras.importers.iiif import *  # noqa: F401, F403
 
-    Returns
-    -------
-    Corpus
-    """
-    importer = IIIFImporter(manifest_url, max_resolution=max_resolution)
-    importer.load()
-    return importer.import_corpus(
-        pages=pages,
-        output_dir=output_dir,
-        show_progress=show_progress,
-    )
+import picarones.extras.importers.iiif as _module
+__all__ = getattr(_module, "__all__", [
+    name for name in dir(_module) if not name.startswith("_")
+])

pyproject.toml

@@ -79,9 +79,16 @@ ocr-cloud = [
 # entièrement, et un futur split en package PyPI séparé
 # ``picarones-historical`` réutilisera ce nom d'extra.
 historical = []
+# Importeurs de corpus depuis sources distantes (Cercle 3, phase C).
+# Les 6 importeurs (``picarones.extras.importers.*``) sont livrés dans
+# le package principal. ``[importers]`` documente l'intention de
+# séparation future en package PyPI ``picarones-importers``. Les
+# modules ``huggingface`` et ``escriptorium`` émettent un
+# ``UserWarning`` à l'import (statut expérimental).
+importers = []
 # Installation complète (tous les extras sauf les OCR cloud)
 all = [
-    "picarones[web,hf,llm,dev,historical]",
+    "picarones[web,hf,llm,dev,historical,importers]",
 ]
 
 [project.scripts]

tests/test_phaseC_migration.py

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