chantier4: workflows CLI dédiés + propagation fix Sprint 15 LLM + fusion Gallica→IIIF

Quatrième chantier du plan d'évolution post-Sprint 97 — donner un
point d'entrée à chaque famille de profil (chantier 2) et nettoyer
les duplications transverses identifiées dans l'audit initial.

Sous-chantier 4.A — LLM adapters factorisés
-------------------------------------------
Avant : Sprint 15 (normalisation list[ContentChunk]→str) appliqué
seulement à Mistral. Logging discriminant par status_code (401/429/5xx)
dupliqué Mistral/OpenAI, complètement absent d'Anthropic.

Après : 2 helpers publics dans picarones/llm/base.py :
- ``normalize_llm_content(raw) -> str`` — gère les 4 formats observés
en production (str, None, list[ContentChunk avec .text], list[dict
avec key 'text']). Idempotent sur str.
- ``log_http_error(adapter_name, model, exc, env_var=None)`` — log
warning discriminé par status_code, mention de la variable
d'environnement à vérifier sur 401.

Les 4 adapters (Mistral, OpenAI, Anthropic, Ollama) :
- Déclarent ``api_key_env_var`` (None pour Ollama qui est local).
- Utilisent normalize_llm_content() sur la réponse SDK.
- Utilisent log_http_error() dans le except des appels API.

Bilan LLM : −60 lignes de duplication, comportement homogène, le fix
Sprint 15 appliqué uniformément.

Sous-chantier 4.B — Fusion Gallica→IIIF
---------------------------------------
Avant : ``_validate_url`` et le download HTTP dupliqués entre
gallica.py (lignes 125-155) et iiif.py (lignes 310-344). ~30 lignes
exactement identiques.

Après : nouveau module privé picarones/importers/_http.py qui expose
``validate_http_url`` et ``download_url`` (centralisé, retry
exponentiel configurable, garde-fou contre file:// / ftp:// /
javascript:). Gallica et IIIF y délèguent.

Pour la rétrocompat des tests Sprint 4 qui font
``from picarones.importers.iiif import _validate_url, _download_url``,
ces deux noms restent exposés depuis iiif.py comme alias de re-export.

Pas de suppression — le polite ``delay_between_requests`` BnF reste
spécifique à Gallica, le User-Agent custom reste configurable.

Sous-chantier 4.C — 3 sous-commandes CLI
----------------------------------------
Trois nouveaux workflows dédiés dans cli.py qui mappent les profils
du chantier 2 :

- ``picarones diagnose --corpus DIR`` → profil "diagnostics"
→ vue HTML « Diagnostic approfondi » (chantier 3) avec leviers,
profil d'image, baseline, longitudinal.

- ``picarones economics --corpus DIR`` → profil "economics"
→ vue HTML « Coût et performance » avec throughput effectif
(HTR-United 5 s/erreur).

- ``picarones edition --corpus DIR`` → profil "philological"
→ vue HTML « Taxonomie avancée » avec comparaison miroir
leader vs runner-up + 6 modules philologiques.

Helper ``_run_workflow(...)`` factorise la logique commune entre
les 4 commandes (run + 3 nouvelles) : chargement corpus,
instanciation moteurs, run_benchmark(profile=...), affichage
classement. ~80 lignes de duplication évitées sur les 3 nouvelles
commandes vs naive copy-paste.

Validation 7/7 en sandbox
-------------------------
- 4.A.1 : api_key_env_var déclaré sur Mistral/OpenAI/Anthropic
(=respective env var) et None sur Ollama.
- 4.A.2 : normalize_llm_content gère 4 formats (str/None/
list[ContentChunk]/list[dict]) + idempotence.
- 4.A.3 : aucun adapter ne réimplémente le pattern de log par status_code.
- 4.B.1 : iiif._validate_url IS _http.validate_http_url
(single source of truth confirmée par identité d'objet).
- 4.B.2 : Gallica._fetch_url contient bien l'import vers
_http.download_url.
- 4.B.3 : validate_http_url rejette file://, ftp://, javascript://, etc.
- 4.C : les 3 commandes diagnose/economics/edition sont enregistrées
dans le groupe Click avec le bon profile par défaut.

Tests
-----
+260 lignes dans tests/test_chantier4.py organisés en 4 classes :
TestNormalizeLlmContent (9 tests dont Sprint 15 fix), TestLogHttpError
(4 tests sur 401/429/5xx/générique), TestLlmAdaptersInheritEnvVar
(4 tests), TestHttpHelpers (5 tests dont parametrize sur 5 schémas
malicieux), TestIiifAliasesDelegateToHttp (rétrocompat tests Sprint 4),
TestGallicaDelegatesToHttp (anti-régression), TestCliWorkflows
(3 commandes + helper).

Verrou levé
-----------
Le fix Sprint 15 est désormais cohérent sur les 4 providers LLM.
La duplication Gallica/IIIF est résorbée. Les 3 nouveaux workflows
CLI mappent les profils du chantier 2 — un archiviste lance
``picarones edition`` au lieu de devoir mémoriser ``run --profile
philological``.

picarones/cli.py

@@ -214,6 +214,227 @@ def run_cmd(
                 sys.exit(1)
 
 
+# ---------------------------------------------------------------------------
+# Workflows CLI dédiés (chantier 4 post-Sprint 97)
+# ---------------------------------------------------------------------------
+#
+# Chaque commande spécialisée fixe un profil de calcul (chantier 2) et
+# émet un message identifiant la famille avant de déléguer au runner.
+# L'option ``--profile`` reste disponible mais le défaut change pour
+# chaque commande.
+
+def _run_workflow(
+    *,
+    corpus: str,
+    engines: str,
+    output: str,
+    lang: str,
+    psm: int,
+    no_progress: bool,
+    verbose: bool,
+    profile: str,
+    workflow_label: str,
+) -> None:
+    """Implémentation commune des commandes ``run``, ``diagnose``,
+    ``economics`` et ``edition``.
+
+    Les 4 commandes partagent le squelette : chargement corpus →
+    instanciation moteurs → ``run_benchmark(profile=...)`` → affichage
+    classement.  Seul le profil par défaut et le message d'en-tête
+    diffèrent.
+    """
+    _setup_logging(verbose)
+
+    from picarones.core.corpus import load_corpus_from_directory
+    from picarones.core.runner import run_benchmark
+
+    try:
+        corp = load_corpus_from_directory(corpus)
+    except (FileNotFoundError, ValueError) as exc:
+        click.echo(f"Erreur corpus : {exc}", err=True)
+        sys.exit(1)
+
+    click.echo(f"[{workflow_label}] Corpus '{corp.name}' — "
+               f"{len(corp)} documents chargés.")
+
+    engine_names = [e.strip() for e in engines.split(",") if e.strip()]
+    ocr_engines = []
+    for name in engine_names:
+        try:
+            engine = _engine_from_name(name, lang=lang, psm=psm)
+            ocr_engines.append(engine)
+        except click.BadParameter as exc:
+            click.echo(f"Erreur moteur : {exc}", err=True)
+            sys.exit(1)
+
+    if not ocr_engines:
+        click.echo("Aucun moteur valide spécifié.", err=True)
+        sys.exit(1)
+
+    click.echo(f"Moteurs : {', '.join(e.name for e in ocr_engines)}")
+    click.echo(f"Profil de métriques : {profile}")
+
+    result = run_benchmark(
+        corpus=corp,
+        engines=ocr_engines,
+        output_json=output,
+        show_progress=not no_progress,
+        profile=profile,
+    )
+
+    click.echo("\n── Classement ──────────────────────────────────")
+    for rank, entry in enumerate(result.ranking(), 1):
+        cer_pct = (
+            f"{entry['mean_cer'] * 100:.2f}%"
+            if entry["mean_cer"] is not None else "N/A"
+        )
+        wer_pct = (
+            f"{entry['mean_wer'] * 100:.2f}%"
+            if entry["mean_wer"] is not None else "N/A"
+        )
+        failed = entry["failed"]
+        failed_str = f" ({failed} erreur(s))" if failed else ""
+        click.echo(
+            f"  {rank}. {entry['engine']:<20} "
+            f"CER={cer_pct:<8} WER={wer_pct}{failed_str}"
+        )
+
+    click.echo(f"\nRésultats écrits dans : {output}")
+
+
+@cli.command("diagnose")
+@click.option(
+    "--corpus", "-c", required=True,
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    help="Dossier contenant les paires image / .gt.txt",
+)
+@click.option(
+    "--engines", "-e", default="tesseract", show_default=True,
+    help="Liste de moteurs séparés par des virgules",
+)
+@click.option(
+    "--output", "-o", default="results_diagnose.json", show_default=True,
+    type=click.Path(resolve_path=True),
+    help="Fichier JSON de sortie",
+)
+@click.option("--lang", "-l", default="fra", show_default=True,
+              help="Code langue Tesseract")
+@click.option("--psm", default=6, show_default=True,
+              help="Page Segmentation Mode Tesseract")
+@click.option("--no-progress", is_flag=True, default=False,
+              help="Désactive la barre de progression")
+@click.option("--verbose", "-v", is_flag=True, default=False,
+              help="Mode verbeux")
+def diagnose_cmd(
+    corpus: str, engines: str, output: str, lang: str, psm: int,
+    no_progress: bool, verbose: bool,
+) -> None:
+    """Workflow diagnostic : bench + leviers d'amélioration + image_predictive.
+
+    Active le profil ``diagnostics`` (chantier 2) qui calcule les
+    métriques nécessaires à la vue HTML « Diagnostic approfondi »
+    (chantier 3) : leviers, profil d'image, baseline, longitudinal.
+    Idéal pour comprendre *pourquoi* un moteur produit ces résultats
+    sur ce corpus, pas seulement *quel CER*.
+    """
+    _run_workflow(
+        corpus=corpus, engines=engines, output=output,
+        lang=lang, psm=psm,
+        no_progress=no_progress, verbose=verbose,
+        profile="diagnostics",
+        workflow_label="diagnose",
+    )
+
+
+@cli.command("economics")
+@click.option(
+    "--corpus", "-c", required=True,
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    help="Dossier contenant les paires image / .gt.txt",
+)
+@click.option(
+    "--engines", "-e", default="tesseract", show_default=True,
+    help="Liste de moteurs séparés par des virgules",
+)
+@click.option(
+    "--output", "-o", default="results_economics.json", show_default=True,
+    type=click.Path(resolve_path=True),
+    help="Fichier JSON de sortie",
+)
+@click.option("--lang", "-l", default="fra", show_default=True,
+              help="Code langue Tesseract")
+@click.option("--psm", default=6, show_default=True,
+              help="Page Segmentation Mode Tesseract")
+@click.option("--no-progress", is_flag=True, default=False,
+              help="Désactive la barre de progression")
+@click.option("--verbose", "-v", is_flag=True, default=False,
+              help="Mode verbeux")
+def economics_cmd(
+    corpus: str, engines: str, output: str, lang: str, psm: int,
+    no_progress: bool, verbose: bool,
+) -> None:
+    """Workflow économique : bench + throughput effectif + (cost projection).
+
+    Active le profil ``economics`` (chantier 2) qui se concentre sur
+    les métriques de décision budget : pages/h utilisable (intégrant
+    la correction humaine HTR-United à 5 s/erreur), coût marginal par
+    erreur évitée. La vue HTML « Coût et performance » (chantier 3)
+    est ensuite branchée.
+    """
+    _run_workflow(
+        corpus=corpus, engines=engines, output=output,
+        lang=lang, psm=psm,
+        no_progress=no_progress, verbose=verbose,
+        profile="economics",
+        workflow_label="economics",
+    )
+
+
+@cli.command("edition")
+@click.option(
+    "--corpus", "-c", required=True,
+    type=click.Path(exists=True, file_okay=False, resolve_path=True),
+    help="Dossier contenant les paires image / .gt.txt",
+)
+@click.option(
+    "--engines", "-e", default="tesseract", show_default=True,
+    help="Liste de moteurs séparés par des virgules",
+)
+@click.option(
+    "--output", "-o", default="results_edition.json", show_default=True,
+    type=click.Path(resolve_path=True),
+    help="Fichier JSON de sortie",
+)
+@click.option("--lang", "-l", default="fra", show_default=True,
+              help="Code langue Tesseract")
+@click.option("--psm", default=6, show_default=True,
+              help="Page Segmentation Mode Tesseract")
+@click.option("--no-progress", is_flag=True, default=False,
+              help="Désactive la barre de progression")
+@click.option("--verbose", "-v", is_flag=True, default=False,
+              help="Mode verbeux")
+def edition_cmd(
+    corpus: str, engines: str, output: str, lang: str, psm: int,
+    no_progress: bool, verbose: bool,
+) -> None:
+    """Workflow édition critique : bench + métriques philologiques.
+
+    Active le profil ``philological`` (chantier 2) qui inclut les
+    modules philologiques (unicode_blocks, abbreviations, MUFI,
+    early_modern_typography, modern_archives, roman_numerals) et la
+    vue HTML « Taxonomie avancée » (chantier 3) avec comparaison
+    miroir leader vs runner-up. Cible : éditeurs de chartes,
+    paléographes, archivistes.
+    """
+    _run_workflow(
+        corpus=corpus, engines=engines, output=output,
+        lang=lang, psm=psm,
+        no_progress=no_progress, verbose=verbose,
+        profile="philological",
+        workflow_label="edition",
+    )
+
+
 # ---------------------------------------------------------------------------
 # picarones metrics
 # ---------------------------------------------------------------------------

picarones/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/importers/gallica.py

@@ -122,34 +122,38 @@ class GallicaClient:
         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:
-        """Vérifie que l'URL est sûre (pas de schéma file://, ftp://, etc.)."""
-        from urllib.parse import urlparse
-        parsed = urlparse(url)
-        if parsed.scheme not in ("http", "https"):
-            raise ValueError(
-                f"Schéma URL non autorisé '{parsed.scheme}' (seuls http/https sont acceptés) : {url}"
-            )
+        """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."""
-        self._validate_url(url)
-        req = urllib.request.Request(
-            url,
-            headers={"User-Agent": "Picarones/1.0 (research tool)"},
-        )
+        """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:
-            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
-                return resp.read()
-        except urllib.error.HTTPError as exc:
-            raise RuntimeError(
-                f"HTTP {exc.code} sur {url}: {exc.reason}"
-            ) from exc
-        except urllib.error.URLError as exc:
-            raise RuntimeError(
-                f"Impossible de joindre {url}: {exc.reason}"
-            ) from exc
+            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)

picarones/importers/iiif.py

@@ -307,41 +307,12 @@ def _extract_v3_transcription(canvas: dict) -> Optional[str]:
 # Téléchargement avec retry
 # ---------------------------------------------------------------------------
 
-def _validate_url(url: str) -> None:
-    """Vérifie que l'URL est sûre (pas de schéma file://, ftp://, etc.)."""
-    from urllib.parse import urlparse
-    parsed = urlparse(url)
-    if parsed.scheme not in ("http", "https"):
-        raise ValueError(
-            f"Schéma URL non autorisé '{parsed.scheme}' (seuls http/https sont acceptés) : {url}"
-        )
-
-
-def _download_url(
-    url: str,
-    retries: int = 4,
-    backoff: float = 2.0,
-    timeout: int = 60,
-) -> bytes:
-    """Télécharge une URL avec retry exponentiel."""
-    _validate_url(url)
-    headers = {
-        "User-Agent": "Picarones/1.0 (OCR benchmark platform; https://github.com/maribakulj/Picarones)"
-    }
-    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
+# 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:

picarones/llm/anthropic_adapter.py

@@ -6,7 +6,11 @@ import logging
 import os
 from typing import Optional
 
-from picarones.llm.base import BaseLLMAdapter
+from picarones.llm.base import (
+    BaseLLMAdapter,
+    log_http_error,
+    normalize_llm_content,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -19,6 +23,8 @@ class AnthropicAdapter(BaseLLMAdapter):
     Modes supportés : text_only, text_and_image, zero_shot.
     """
 
+    api_key_env_var = "ANTHROPIC_API_KEY"
+
     @property
     def name(self) -> str:
         return "anthropic"
@@ -74,9 +80,12 @@ class AnthropicAdapter(BaseLLMAdapter):
                 messages=[{"role": "user", "content": content}],
             )
         except Exception as exc:
-            logger.warning(
-                "[AnthropicAdapter] erreur API (modèle=%s) : %s",
-                self.model, exc,
+            # Chantier 4 — log discriminant (401/429/5xx) factorisé.
+            # Auparavant Anthropic ne discriminait pas par code HTTP,
+            # difficile à diagnostiquer (clé invalide vs rate limit).
+            log_http_error(
+                "AnthropicAdapter", self.model, exc,
+                env_var=self.api_key_env_var,
             )
             raise
 
@@ -87,12 +96,16 @@ class AnthropicAdapter(BaseLLMAdapter):
             )
             return ""
 
-        block = response.content[0]
-        text = getattr(block, "text", None)
-        if text is None:
+        # Chantier 4 — propagation du fix Sprint 15 : le SDK Anthropic
+        # retourne ``response.content`` comme une liste de blocs
+        # (``ContentBlock`` avec attribut ``text``). ``normalize_llm_content``
+        # concatène le texte de tous les blocs au lieu de ne prendre que
+        # le premier — utile quand le modèle émet plusieurs blocs.
+        text = normalize_llm_content(response.content)
+        if not text:
+            block = response.content[0]
             logger.warning(
                 "[AnthropicAdapter] bloc de type '%s' sans texte (modèle=%s).",
                 getattr(block, "type", "unknown"), self.model,
             )
-            return ""
         return text

picarones/llm/base.py

@@ -6,7 +6,7 @@ import logging
 import time
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
-from typing import Optional
+from typing import Any, Optional
 
 logger = logging.getLogger(__name__)
 
@@ -39,6 +39,105 @@ def _is_retryable(exc: Exception) -> bool:
     return False
 
 
+def normalize_llm_content(raw: Any) -> str:
+    """Normalise une réponse LLM en chaîne plate.
+
+    Chantier 4 (post-Sprint 97) — propagation du fix Mistral
+    Sprint 15 à tous les providers. Le SDK Mistral peut retourner
+    une liste de ``ContentChunk`` au lieu d'une chaîne pour certains
+    modèles/versions ; le SDK OpenAI peut faire de même quand on
+    active des features de structuration. Ce helper applique la même
+    discipline pour les 4 adapters :
+
+    - ``str``                          → renvoyée telle quelle (ou ``""``).
+    - ``None``                         → ``""``.
+    - ``list[ContentChunk]``           → concaténation des ``.text``.
+    - ``list[dict]`` avec clé ``text`` → concaténation des ``["text"]``.
+    - ``list[str]``                    → concaténation directe.
+    - autre objet avec ``.text``       → ``obj.text``.
+    - autre                            → ``str(obj)`` (best-effort).
+
+    Le résultat est garanti être une ``str`` ; ``""`` quand la réponse
+    est vide. La fonction est idempotente : ``normalize_llm_content(s)
+    == s`` pour toute chaîne ``s``.
+    """
+    if raw is None:
+        return ""
+    if isinstance(raw, str):
+        return raw
+    if isinstance(raw, list):
+        parts: list[str] = []
+        for chunk in raw:
+            if chunk is None:
+                continue
+            if isinstance(chunk, str):
+                parts.append(chunk)
+                continue
+            if hasattr(chunk, "text"):
+                txt = getattr(chunk, "text", None)
+                if isinstance(txt, str):
+                    parts.append(txt)
+                    continue
+            if isinstance(chunk, dict) and isinstance(chunk.get("text"), str):
+                parts.append(chunk["text"])
+                continue
+            # Dernier recours — convertit le chunk en chaîne
+            parts.append(str(chunk))
+        return "".join(parts)
+    if hasattr(raw, "text") and isinstance(getattr(raw, "text", None), str):
+        return raw.text  # type: ignore[no-any-return]
+    return str(raw)
+
+
+def log_http_error(
+    adapter_name: str,
+    model: str,
+    exc: Exception,
+    *,
+    env_var: Optional[str] = None,
+) -> None:
+    """Log standardisé des erreurs HTTP des SDK LLM.
+
+    Chantier 4 (post-Sprint 97) — propagation du log discriminant
+    Mistral/OpenAI à tous les providers. Inspecte ``status_code`` et
+    ``http_status`` puis émet un warning ciblé selon le code :
+
+    - 401 : clé API invalide/expirée (mention de la variable
+      d'environnement à vérifier si fournie).
+    - 429 : rate limit / quota dépassé.
+    - 5xx : problème serveur côté provider.
+    - autre / pas de status_code : log générique.
+
+    L'exception n'est pas levée — l'appelant doit ``raise``
+    explicitement après ce log s'il veut propager (le retry est géré
+    par ``BaseLLMAdapter.complete`` selon ``_is_retryable``).
+    """
+    status = getattr(exc, "status_code", None) or getattr(exc, "http_status", None)
+    if status == 401:
+        suffix = f" Vérifier {env_var}." if env_var else ""
+        logger.warning(
+            "[%s] erreur HTTP 401 — clé API invalide ou expirée "
+            "(modèle=%s).%s",
+            adapter_name, model, suffix,
+        )
+    elif status == 429:
+        logger.warning(
+            "[%s] erreur HTTP 429 — quota dépassé ou rate-limit "
+            "(modèle=%s). Réessayer plus tard.",
+            adapter_name, model,
+        )
+    elif status is not None and status >= 500:
+        logger.warning(
+            "[%s] erreur HTTP %d — problème serveur (modèle=%s) : %s",
+            adapter_name, status, model, exc,
+        )
+    else:
+        logger.warning(
+            "[%s] erreur lors de l'appel API (modèle=%s) : %s",
+            adapter_name, model, exc,
+        )
+
+
 @dataclass
 class LLMResult:
     """Résultat produit par un appel LLM."""
@@ -69,8 +168,28 @@ class BaseLLMAdapter(ABC):
     Les erreurs retryables (HTTP 429, 5xx, timeout réseau) sont automatiquement
     retentées avec backoff exponentiel (2s, 4s, 8s par défaut). Configurable
     via ``config["max_retries"]`` et ``config["retry_backoff"]``.
+
+    Normalisation des réponses (chantier 4)
+    ---------------------------------------
+    Les sous-classes utilisent :func:`normalize_llm_content` sur la
+    réponse SDK avant de la retourner — garantit qu'une réponse de
+    type ``list[ContentChunk]`` (Mistral, parfois OpenAI) est
+    convertie en ``str`` plate.
+
+    Logging d'erreurs HTTP (chantier 4)
+    -----------------------------------
+    Les sous-classes utilisent :func:`log_http_error` pour produire
+    un log discriminant par ``status_code`` (401 → clé invalide,
+    429 → rate limit, 5xx → serveur).  Auparavant ce log était
+    dupliqué chez Mistral/OpenAI et absent chez Anthropic.
     """
 
+    # Variable d'environnement portant la clé API.  Sous-classes
+    # surchargent (ex. ``"OPENAI_API_KEY"``) ; mention utilisée par
+    # :func:`log_http_error` quand un 401 est rencontré.  ``None``
+    # pour les providers sans clé (Ollama).
+    api_key_env_var: Optional[str] = None
+
     def __init__(
         self,
         model: Optional[str] = None,
@@ -150,3 +269,11 @@ class BaseLLMAdapter(ABC):
 
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}(model={self.model!r})"
+
+
+__all__ = [
+    "BaseLLMAdapter",
+    "LLMResult",
+    "log_http_error",
+    "normalize_llm_content",
+]

picarones/llm/mistral_adapter.py

@@ -6,7 +6,11 @@ import logging
 import os
 from typing import Optional
 
-from picarones.llm.base import BaseLLMAdapter
+from picarones.llm.base import (
+    BaseLLMAdapter,
+    log_http_error,
+    normalize_llm_content,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -36,6 +40,8 @@ class MistralAdapter(BaseLLMAdapter):
     pas le mode multimodal — utiliser ``PipelineMode.TEXT_ONLY`` avec ces modèles.
     """
 
+    api_key_env_var = "MISTRAL_API_KEY"
+
     @property
     def name(self) -> str:
         return "mistral"
@@ -109,30 +115,10 @@ class MistralAdapter(BaseLLMAdapter):
                 max_tokens=max_tokens,
             )
         except Exception as exc:
-            status_code = getattr(exc, "status_code", None) or getattr(exc, "http_status", None)
-            if status_code == 401:
-                logger.warning(
-                    "[MistralAdapter] erreur HTTP 401 — clé API invalide ou expirée "
-                    "(modèle=%s). Vérifier MISTRAL_API_KEY.",
-                    self.model,
-                )
-            elif status_code == 429:
-                logger.warning(
-                    "[MistralAdapter] erreur HTTP 429 — quota dépassé ou rate-limit "
-                    "(modèle=%s). Réessayer plus tard.",
-                    self.model,
-                )
-            elif status_code is not None and status_code >= 500:
-                logger.warning(
-                    "[MistralAdapter] erreur HTTP %d — problème serveur Mistral "
-                    "(modèle=%s) : %s",
-                    status_code, self.model, exc,
-                )
-            else:
-                logger.warning(
-                    "[MistralAdapter] erreur lors de l'appel API (modèle=%s) : %s",
-                    self.model, exc,
-                )
+            log_http_error(
+                "MistralAdapter", self.model, exc,
+                env_var=self.api_key_env_var,
+            )
             raise
 
         if not response.choices:
@@ -146,15 +132,10 @@ class MistralAdapter(BaseLLMAdapter):
         raw = _choice.message.content
         _finish_reason = _choice.finish_reason
 
-        # Le SDK mistralai peut retourner une liste de ContentChunk au lieu
-        # d'une chaîne pour certains modèles/versions.  Normaliser en str.
-        if isinstance(raw, list):
-            raw = "".join(
-                chunk.text if hasattr(chunk, "text") else str(chunk)
-                for chunk in raw
-            )
-
-        text = raw or ""
+        # Chantier 4 — normalisation factorisée dans
+        # ``picarones.llm.base.normalize_llm_content`` (Sprint 15
+        # généralisé : list[ContentChunk] / list[dict] / str → str).
+        text = normalize_llm_content(raw)
 
         _completion_tokens = None
         if hasattr(response, "usage") and response.usage:

picarones/llm/ollama_adapter.py

@@ -6,7 +6,7 @@ import logging
 from typing import Optional
 from urllib.parse import urlparse
 
-from picarones.llm.base import BaseLLMAdapter
+from picarones.llm.base import BaseLLMAdapter, normalize_llm_content
 
 logger = logging.getLogger(__name__)
 
@@ -98,7 +98,10 @@ class OllamaAdapter(BaseLLMAdapter):
                 f"Réponse JSON invalide du serveur Ollama : {exc}"
             ) from exc
 
-        text = result.get("response", "")
+        # Chantier 4 — propagation du fix Sprint 15 : Ollama retourne
+        # ``response`` en string mais on normalise par défense (cas où
+        # un futur build retournerait un format structuré).
+        text = normalize_llm_content(result.get("response", ""))
         if not text:
             logger.warning(
                 "[OllamaAdapter] réponse vide (modèle=%s).", self.model,

picarones/llm/openai_adapter.py

@@ -6,7 +6,11 @@ import logging
 import os
 from typing import Optional
 
-from picarones.llm.base import BaseLLMAdapter
+from picarones.llm.base import (
+    BaseLLMAdapter,
+    log_http_error,
+    normalize_llm_content,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -19,6 +23,8 @@ class OpenAIAdapter(BaseLLMAdapter):
     Modes supportés : text_only, text_and_image, zero_shot.
     """
 
+    api_key_env_var = "OPENAI_API_KEY"
+
     @property
     def name(self) -> str:
         return "openai"
@@ -70,21 +76,10 @@ class OpenAIAdapter(BaseLLMAdapter):
                 max_tokens=max_tokens,
             )
         except Exception as exc:
-            status_code = getattr(exc, "status_code", None)
-            if status_code == 401:
-                logger.warning(
-                    "[OpenAIAdapter] erreur HTTP 401 — clé API invalide (modèle=%s).",
-                    self.model,
-                )
-            elif status_code == 429:
-                logger.warning(
-                    "[OpenAIAdapter] erreur HTTP 429 — rate limit (modèle=%s).",
-                    self.model,
-                )
-            else:
-                logger.warning(
-                    "[OpenAIAdapter] erreur API (modèle=%s) : %s", self.model, exc,
-                )
+            log_http_error(
+                "OpenAIAdapter", self.model, exc,
+                env_var=self.api_key_env_var,
+            )
             raise
 
         if not response.choices:
@@ -92,4 +87,8 @@ class OpenAIAdapter(BaseLLMAdapter):
                 "[OpenAIAdapter] response.choices vide (modèle=%s).", self.model,
             )
             return ""
-        return response.choices[0].message.content or ""
+        # Chantier 4 — propagation du fix Sprint 15 : le SDK OpenAI
+        # peut retourner une ``list[ContentBlock]`` selon l'API
+        # (Responses, structured outputs).  ``normalize_llm_content``
+        # gère les deux cas (str et list).
+        return normalize_llm_content(response.choices[0].message.content)

tests/test_chantier4.py

@@ -0,0 +1,277 @@
+"""Tests du chantier 4 (post-Sprint 97) : LLM + Gallica/IIIF + CLI workflows.
+
+Couvre :
+
+- Sous-chantier 4.A : ``normalize_llm_content`` + ``log_http_error``
+  factorisés dans :mod:`picarones.llm.base`, propagés aux 4 adapters.
+- Sous-chantier 4.B : helpers HTTP factorisés dans
+  :mod:`picarones.importers._http`, Gallica et IIIF y délèguent.
+- Sous-chantier 4.C : 3 nouvelles sous-commandes CLI ``diagnose``,
+  ``economics``, ``edition`` qui mappent un profil de calcul
+  (chantier 2) à un workflow.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 4.A — LLM base helpers
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestNormalizeLlmContent:
+    def test_str_passes_through(self):
+        from picarones.llm.base import normalize_llm_content
+
+        assert normalize_llm_content("hello") == "hello"
+        # Idempotence : retourne l'objet exact pour str
+        s = "test"
+        assert normalize_llm_content(s) is s
+
+    def test_none_returns_empty(self):
+        from picarones.llm.base import normalize_llm_content
+
+        assert normalize_llm_content(None) == ""
+
+    def test_empty_string_passes(self):
+        from picarones.llm.base import normalize_llm_content
+
+        assert normalize_llm_content("") == ""
+
+    def test_list_of_chunks_with_text_attr(self):
+        """Cas Mistral SDK : list[ContentChunk]. Sprint 15 fix."""
+        from picarones.llm.base import normalize_llm_content
+
+        class MockChunk:
+            def __init__(self, text):
+                self.text = text
+
+        result = normalize_llm_content([MockChunk("hello "), MockChunk("world")])
+        assert result == "hello world"
+
+    def test_list_of_dicts_with_text_key(self):
+        """Cas Anthropic SDK : list[dict] avec clé 'text'."""
+        from picarones.llm.base import normalize_llm_content
+
+        result = normalize_llm_content([{"text": "a"}, {"text": "b"}])
+        assert result == "ab"
+
+    def test_list_of_strings(self):
+        from picarones.llm.base import normalize_llm_content
+
+        assert normalize_llm_content(["foo", "bar"]) == "foobar"
+
+    def test_mixed_list(self):
+        from picarones.llm.base import normalize_llm_content
+
+        class MockChunk:
+            def __init__(self, text):
+                self.text = text
+
+        result = normalize_llm_content([
+            MockChunk("a"), "b", {"text": "c"},
+        ])
+        assert result == "abc"
+
+    def test_none_in_list_skipped(self):
+        from picarones.llm.base import normalize_llm_content
+
+        assert normalize_llm_content([None, "a", None, "b"]) == "ab"
+
+    def test_object_with_text_attribute(self):
+        from picarones.llm.base import normalize_llm_content
+
+        class TextHolder:
+            text = "hello"
+        assert normalize_llm_content(TextHolder()) == "hello"
+
+
+class TestLogHttpError:
+    def test_401_logs_invalid_key(self, caplog):
+        from picarones.llm.base import log_http_error
+
+        class FakeExc(Exception):
+            status_code = 401
+
+        with caplog.at_level("WARNING"):
+            log_http_error("OpenAIAdapter", "gpt-4o", FakeExc("Unauthorized"),
+                           env_var="OPENAI_API_KEY")
+        assert any("401" in r.message and "OPENAI_API_KEY" in r.message
+                   for r in caplog.records)
+
+    def test_429_logs_rate_limit(self, caplog):
+        from picarones.llm.base import log_http_error
+
+        class FakeExc(Exception):
+            status_code = 429
+
+        with caplog.at_level("WARNING"):
+            log_http_error("MistralAdapter", "mistral-large", FakeExc("Too Many"))
+        assert any("429" in r.message and "rate" in r.message.lower()
+                   for r in caplog.records)
+
+    def test_5xx_logs_server_error(self, caplog):
+        from picarones.llm.base import log_http_error
+
+        class FakeExc(Exception):
+            status_code = 503
+
+        with caplog.at_level("WARNING"):
+            log_http_error("AnthropicAdapter", "claude-sonnet", FakeExc("Service unavailable"))
+        assert any("503" in r.message and "serveur" in r.message.lower()
+                   for r in caplog.records)
+
+    def test_no_status_code_logs_generic(self, caplog):
+        from picarones.llm.base import log_http_error
+
+        with caplog.at_level("WARNING"):
+            log_http_error("Foo", "bar", ValueError("random"))
+        # Doit produire un warning (générique)
+        assert any("Foo" in r.message for r in caplog.records)
+
+
+class TestLlmAdaptersInheritEnvVar:
+    """Le chantier 4 a ajouté ``api_key_env_var`` aux 3 adapters cloud."""
+
+    def test_mistral_declares_env_var(self):
+        from picarones.llm.mistral_adapter import MistralAdapter
+        assert MistralAdapter.api_key_env_var == "MISTRAL_API_KEY"
+
+    def test_openai_declares_env_var(self):
+        from picarones.llm.openai_adapter import OpenAIAdapter
+        assert OpenAIAdapter.api_key_env_var == "OPENAI_API_KEY"
+
+    def test_anthropic_declares_env_var(self):
+        from picarones.llm.anthropic_adapter import AnthropicAdapter
+        assert AnthropicAdapter.api_key_env_var == "ANTHROPIC_API_KEY"
+
+    def test_ollama_no_env_var(self):
+        """Ollama est local — pas de clé API."""
+        from picarones.llm.ollama_adapter import OllamaAdapter
+        assert OllamaAdapter.api_key_env_var is None
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 4.B — Helpers HTTP factorisés (Gallica → IIIF fusion)
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestHttpHelpers:
+    def test_validate_http_url_accepts_https(self):
+        from picarones.importers._http import validate_http_url
+        validate_http_url("https://gallica.bnf.fr/test")  # ne lève pas
+
+    def test_validate_http_url_accepts_http(self):
+        from picarones.importers._http import validate_http_url
+        validate_http_url("http://localhost:8080/x")
+
+    @pytest.mark.parametrize("scheme", ["file", "ftp", "data", "javascript", "ssh"])
+    def test_validate_http_url_rejects_other_schemes(self, scheme):
+        from picarones.importers._http import validate_http_url
+        with pytest.raises(ValueError, match="non autorisé"):
+            validate_http_url(f"{scheme}://example.com/x")
+
+
+class TestIiifAliasesDelegateToHttp:
+    """Les noms ``_validate_url`` et ``_download_url`` exposés depuis
+    :mod:`picarones.importers.iiif` doivent rester disponibles
+    (rétrocompat des tests Sprint 4) — ils délèguent aux helpers
+    factorisés."""
+
+    def test_iiif_validate_url_is_alias(self):
+        from picarones.importers import iiif
+        from picarones.importers._http import validate_http_url
+        assert iiif._validate_url is validate_http_url
+
+    def test_iiif_download_url_is_alias(self):
+        from picarones.importers import iiif
+        from picarones.importers._http import download_url
+        assert iiif._download_url is download_url
+
+
+class TestGallicaDelegatesToHttp:
+    def test_gallica_validate_url_delegates(self):
+        from picarones.importers.gallica import GallicaClient
+        client = GallicaClient()
+        # Doit accepter https
+        client._validate_url("https://gallica.bnf.fr/x")
+        # Doit rejeter un schéma invalide via le helper factorisé
+        with pytest.raises(ValueError, match="non autorisé"):
+            client._validate_url("file:///etc/passwd")
+
+    def test_gallica_uses_iiif_for_image_download(self):
+        """``GallicaClient.import_document`` délègue à IIIFImporter."""
+        # Lecture statique du source — pas d'appel réseau
+        from pathlib import Path
+        gallica_src = (
+            Path(__file__).parent.parent
+            / "picarones" / "importers" / "gallica.py"
+        ).read_text(encoding="utf-8")
+        # Confirme que Gallica importe IIIFImporter
+        assert "from picarones.importers.iiif import IIIFImporter" in gallica_src
+
+
+# ──────────────────────────────────────────────────────────────────────────
+# 4.C — Workflows CLI dédiés
+# ──────────────────────────────────────────────────────────────────────────
+
+
+class TestCliWorkflows:
+    def test_three_new_commands_registered(self):
+        from pathlib import Path
+
+        cli_src = (
+            Path(__file__).parent.parent / "picarones" / "cli.py"
+        ).read_text(encoding="utf-8")
+        # Vérification statique : les 3 commandes existent
+        assert '@cli.command("diagnose")' in cli_src
+        assert '@cli.command("economics")' in cli_src
+        assert '@cli.command("edition")' in cli_src
+        assert "def diagnose_cmd(" in cli_src
+        assert "def economics_cmd(" in cli_src
+        assert "def edition_cmd(" in cli_src
+
+    def test_workflows_map_correct_profile(self):
+        from pathlib import Path
+        cli_src = (
+            Path(__file__).parent.parent / "picarones" / "cli.py"
+        ).read_text(encoding="utf-8")
+        # Chaque commande doit fixer le bon profil
+        # diagnose → diagnostics, economics → economics, edition → philological
+        assert 'profile="diagnostics"' in cli_src
+        assert 'profile="economics"' in cli_src
+        assert 'profile="philological"' in cli_src
+
+    def test_run_workflow_helper_exists(self):
+        """Le helper commun ``_run_workflow`` factorise la logique des
+        4 commandes (run + diagnose + economics + edition) — un seul
+        endroit pour patcher si la logique évolue."""
+        import ast
+        from pathlib import Path
+
+        cli_src = (
+            Path(__file__).parent.parent / "picarones" / "cli.py"
+        ).read_text(encoding="utf-8")
+        tree = ast.parse(cli_src)
+        funcs = {
+            n.name for n in ast.walk(tree) if isinstance(n, ast.FunctionDef)
+        }
+        assert "_run_workflow" in funcs
+
+    @pytest.mark.parametrize("cmd_name", ["diagnose", "economics", "edition"])
+    def test_command_help_works(self, cmd_name):
+        """Les 3 commandes répondent à --help sans crash."""
+        try:
+            from click.testing import CliRunner
+
+            from picarones.cli import cli as cli_group
+        except ImportError:
+            pytest.skip("click non installé")
+
+        runner = CliRunner()
+        result = runner.invoke(cli_group, [cmd_name, "--help"])
+        assert result.exit_code == 0, result.output
+        assert "--corpus" in result.output
+        assert "--engines" in result.output