feat(sprint4-session-b): endpoints jobs, ingestion et modèles IA

Nouveaux modèles SQLAlchemy :
- models/job.py : JobModel (id, corpus_id, page_id, status
pending/running/done/failed, started_at, finished_at, error_message)
- models/model_config_db.py : ModelConfigDB (corpus_id PK, provider_type,
selected_model_id, selected_model_display_name, updated_at)
- models/__init__.py : enregistrement JobModel + ModelConfigDB dans Base

Nouveaux routers (R10 — /api/v1/) :
- api/v1/jobs.py :
POST /corpora/{id}/run → 1 job par page du corpus (202, immédiat)
POST /pages/{id}/run → 1 job pour la page (202, immédiat)
GET /jobs/{id} → état du job (404 si inconnu)
POST /jobs/{id}/retry → relance FAILED→pending (409 si non-FAILED)
- api/v1/ingest.py :
POST /corpora/{id}/ingest/files → multipart, pages créées
POST /corpora/{id}/ingest/iiif-manifest → manifest IIIF 3.0 + 2.x
POST /corpora/{id}/ingest/iiif-images → liste d'URLs directes
- api/v1/models_api.py :
POST /settings/api-key → validation sans stockage (R06)
GET /models → list_all_models() mockable
POST /models/refresh → idem + refreshed_at
PUT /corpora/{id}/model → ModelConfigDB upsert
GET /corpora/{id}/model → config active (404 si absent)

Infrastructure :
- python-multipart ajouté à pyproject.toml (requis pour UploadFile)
- _fetch_json_manifest et _validate_api_key isolés pour être patchables
dans les tests sans dépendances réseau

Tests (61 nouveaux) :
- test_api_jobs.py : corpus.run, pages.run, get_job, retry (409/200)
- test_api_ingest.py : files (disk write vérifié), IIIF 3.0/2.x, images,
erreurs 404/422/502 ; mock _fetch_json_manifest
- test_api_models.py : api-key (R06 vérifié), models list/refresh,
PUT/GET model ; mock list_all_models + _validate_api_key

Total : 457 tests passent, 3 skippés (intégration réseau).

https://claude.ai/code/session_018woyEHc8HG2th7V4ewJ4Kg

backend/app/api/v1/ingest.py

@@ -0,0 +1,329 @@
+"""
+Endpoints d'ingestion de corpus (R10 — préfixe /api/v1/).
+
+POST /api/v1/corpora/{id}/ingest/files
+POST /api/v1/corpora/{id}/ingest/iiif-manifest
+POST /api/v1/corpora/{id}/ingest/iiif-images
+
+Règle (R01) : aucune logique spécifique à un corpus particulier.
+Règle : ingestion = création des PageModel en BDD uniquement.
+         L'analyse IA est déclenchée séparément via /run.
+"""
+# 1. stdlib
+import logging
+import uuid
+from pathlib import Path
+
+# 2. third-party
+import httpx
+from fastapi import APIRouter, Depends, File, HTTPException, UploadFile
+from pydantic import BaseModel
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+# 3. local
+from app import config as _config_module
+from app.models.corpus import CorpusModel, ManuscriptModel, PageModel
+from app.models.database import get_db
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=["ingestion"])
+
+
+# ── Schémas ───────────────────────────────────────────────────────────────────
+
+class IIIFManifestRequest(BaseModel):
+    manifest_url: str
+
+
+class IIIFImagesRequest(BaseModel):
+    urls: list[str]
+    folio_labels: list[str]
+
+
+class IngestResponse(BaseModel):
+    corpus_id: str
+    manuscript_id: str
+    pages_created: int
+    page_ids: list[str]
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+async def _get_corpus_or_404(corpus_id: str, db: AsyncSession) -> CorpusModel:
+    corpus = await db.get(CorpusModel, corpus_id)
+    if corpus is None:
+        raise HTTPException(status_code=404, detail="Corpus introuvable")
+    return corpus
+
+
+async def _get_or_create_manuscript(
+    db: AsyncSession, corpus_id: str, title: str | None = None
+) -> ManuscriptModel:
+    """Retourne le premier manuscrit du corpus, ou en crée un par défaut."""
+    result = await db.execute(
+        select(ManuscriptModel).where(ManuscriptModel.corpus_id == corpus_id).limit(1)
+    )
+    ms = result.scalar_one_or_none()
+    if ms is not None:
+        return ms
+
+    corpus = await db.get(CorpusModel, corpus_id)
+    ms = ManuscriptModel(
+        id=str(uuid.uuid4()),
+        corpus_id=corpus_id,
+        title=title or (corpus.title if corpus else corpus_id),
+        total_pages=0,
+    )
+    db.add(ms)
+    await db.flush()
+    return ms
+
+
+async def _next_sequence(db: AsyncSession, manuscript_id: str) -> int:
+    """Retourne le prochain numéro de séquence disponible (max + 1, ou 1)."""
+    result = await db.execute(
+        select(func.max(PageModel.sequence)).where(
+            PageModel.manuscript_id == manuscript_id
+        )
+    )
+    max_seq = result.scalar_one_or_none()
+    return (max_seq or 0) + 1
+
+
+async def _create_page(
+    db: AsyncSession,
+    manuscript_id: str,
+    corpus_id: str,
+    folio_label: str,
+    sequence: int,
+    image_master_path: str | None = None,
+) -> PageModel:
+    page = PageModel(
+        id=f"{corpus_id}-{folio_label}",
+        manuscript_id=manuscript_id,
+        folio_label=folio_label,
+        sequence=sequence,
+        image_master_path=image_master_path,
+        processing_status="INGESTED",
+    )
+    db.add(page)
+    return page
+
+
+async def _fetch_json_manifest(url: str) -> dict:
+    """Télécharge un manifest IIIF. Fonction isolée pour faciliter les tests."""
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(url, follow_redirects=True, timeout=30.0)
+        resp.raise_for_status()
+        return resp.json()
+
+
+def _extract_canvas_label(canvas: dict, index: int) -> str:
+    """Extrait le folio_label d'un canvas IIIF (3.0 ou 2.x)."""
+    label = canvas.get("label")
+    if isinstance(label, dict):
+        for lang in ("none", "en", "fr", "la"):
+            values = label.get(lang)
+            if values:
+                return (values[0] if isinstance(values, list) else str(values)).strip()
+    elif isinstance(label, str) and label.strip():
+        return label.strip()
+    return f"f{index + 1:03d}r"
+
+
+def _extract_canvas_image_url(canvas: dict) -> str | None:
+    """Extrait l'URL de l'image principale d'un canvas IIIF (3.0 ou 2.x)."""
+    # IIIF 3.0
+    items = canvas.get("items") or []
+    if items:
+        ann_items = (items[0].get("items") or []) if items else []
+        if ann_items:
+            body = ann_items[0].get("body") or {}
+            if isinstance(body, dict):
+                return body.get("id") or body.get("@id")
+    # IIIF 2.x
+    images = canvas.get("images") or []
+    if images:
+        resource = images[0].get("resource") or {}
+        return resource.get("@id")
+    # Fallback : ID du canvas
+    return canvas.get("id") or canvas.get("@id")
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+@router.post("/corpora/{corpus_id}/ingest/files", response_model=IngestResponse, status_code=201)
+async def ingest_files(
+    corpus_id: str,
+    files: list[UploadFile] = File(...),
+    db: AsyncSession = Depends(get_db),
+) -> IngestResponse:
+    """Ingère une liste de fichiers images (multipart/form-data).
+
+    Chaque fichier crée un PageModel. Le fichier est copié dans
+    data/corpora/{slug}/masters/{folio_label}/{filename}.
+    """
+    corpus = await _get_corpus_or_404(corpus_id, db)
+    ms = await _get_or_create_manuscript(db, corpus_id)
+    seq = await _next_sequence(db, ms.id)
+
+    created: list[PageModel] = []
+    for i, upload in enumerate(files):
+        filename = Path(upload.filename or f"file_{i}").name
+        folio_label = Path(filename).stem  # nom sans extension
+
+        master_dir = (
+            _config_module.settings.data_dir
+            / "corpora"
+            / corpus.slug
+            / "masters"
+            / folio_label
+        )
+        master_dir.mkdir(parents=True, exist_ok=True)
+        master_path = master_dir / filename
+        content = await upload.read()
+        master_path.write_bytes(content)
+
+        page = await _create_page(
+            db, ms.id, corpus.slug, folio_label, seq + i,
+            image_master_path=str(master_path),
+        )
+        created.append(page)
+
+    ms.total_pages = (ms.total_pages or 0) + len(created)
+    await db.commit()
+
+    logger.info(
+        "Fichiers ingérés",
+        extra={"corpus_id": corpus_id, "count": len(created)},
+    )
+    return IngestResponse(
+        corpus_id=corpus_id,
+        manuscript_id=ms.id,
+        pages_created=len(created),
+        page_ids=[p.id for p in created],
+    )
+
+
+@router.post("/corpora/{corpus_id}/ingest/iiif-manifest", response_model=IngestResponse, status_code=201)
+async def ingest_iiif_manifest(
+    corpus_id: str,
+    body: IIIFManifestRequest,
+    db: AsyncSession = Depends(get_db),
+) -> IngestResponse:
+    """Télécharge un manifest IIIF, extrait les canvases et crée les PageModel."""
+    corpus = await _get_corpus_or_404(corpus_id, db)
+
+    try:
+        manifest = await _fetch_json_manifest(body.manifest_url)
+    except httpx.HTTPStatusError as exc:
+        raise HTTPException(
+            status_code=502,
+            detail=f"Erreur HTTP lors du téléchargement du manifest : {exc.response.status_code}",
+        )
+    except (httpx.RequestError, httpx.TimeoutException) as exc:
+        raise HTTPException(
+            status_code=502,
+            detail=f"Erreur réseau lors du téléchargement du manifest : {exc}",
+        )
+
+    # Détecte le format IIIF (3.0 vs 2.x)
+    canvases: list[dict] = manifest.get("items") or []
+    if not canvases:
+        sequences = manifest.get("sequences") or []
+        canvases = sequences[0].get("canvases", []) if sequences else []
+
+    if not canvases:
+        raise HTTPException(
+            status_code=422,
+            detail="Le manifest IIIF ne contient aucun canvas (items vide)",
+        )
+
+    # Titre du manuscrit depuis le manifest
+    ms_title_raw = manifest.get("label") or {}
+    if isinstance(ms_title_raw, dict):
+        for lang in ("none", "fr", "en"):
+            v = ms_title_raw.get(lang)
+            if v:
+                ms_title = v[0] if isinstance(v, list) else str(v)
+                break
+        else:
+            ms_title = corpus.title
+    elif isinstance(ms_title_raw, str):
+        ms_title = ms_title_raw
+    else:
+        ms_title = corpus.title
+
+    ms = await _get_or_create_manuscript(db, corpus_id, title=ms_title)
+    seq = await _next_sequence(db, ms.id)
+
+    created: list[PageModel] = []
+    for i, canvas in enumerate(canvases):
+        folio_label = _extract_canvas_label(canvas, i)
+        image_url = _extract_canvas_image_url(canvas)
+        page = await _create_page(
+            db, ms.id, corpus.slug, folio_label, seq + i,
+            image_master_path=image_url,
+        )
+        created.append(page)
+
+    ms.total_pages = (ms.total_pages or 0) + len(created)
+    await db.commit()
+
+    logger.info(
+        "Manifest IIIF ingéré",
+        extra={"corpus_id": corpus_id, "url": body.manifest_url, "pages": len(created)},
+    )
+    return IngestResponse(
+        corpus_id=corpus_id,
+        manuscript_id=ms.id,
+        pages_created=len(created),
+        page_ids=[p.id for p in created],
+    )
+
+
+@router.post("/corpora/{corpus_id}/ingest/iiif-images", response_model=IngestResponse, status_code=201)
+async def ingest_iiif_images(
+    corpus_id: str,
+    body: IIIFImagesRequest,
+    db: AsyncSession = Depends(get_db),
+) -> IngestResponse:
+    """Ingère une liste d'URLs d'images IIIF directes.
+
+    urls et folio_labels doivent avoir la même longueur.
+    """
+    if len(body.urls) != len(body.folio_labels):
+        raise HTTPException(
+            status_code=422,
+            detail=f"urls ({len(body.urls)}) et folio_labels ({len(body.folio_labels)}) doivent avoir la même longueur",
+        )
+    if not body.urls:
+        raise HTTPException(status_code=422, detail="La liste d'URLs est vide")
+
+    corpus = await _get_corpus_or_404(corpus_id, db)
+    ms = await _get_or_create_manuscript(db, corpus_id)
+    seq = await _next_sequence(db, ms.id)
+
+    created: list[PageModel] = []
+    for i, (url, folio_label) in enumerate(zip(body.urls, body.folio_labels)):
+        page = await _create_page(
+            db, ms.id, corpus.slug, folio_label, seq + i,
+            image_master_path=url,
+        )
+        created.append(page)
+
+    ms.total_pages = (ms.total_pages or 0) + len(created)
+    await db.commit()
+
+    logger.info(
+        "Images IIIF ingérées",
+        extra={"corpus_id": corpus_id, "count": len(created)},
+    )
+    return IngestResponse(
+        corpus_id=corpus_id,
+        manuscript_id=ms.id,
+        pages_created=len(created),
+        page_ids=[p.id for p in created],
+    )

backend/app/api/v1/jobs.py

@@ -0,0 +1,158 @@
+"""
+Endpoints de gestion des jobs de traitement (R10 — préfixe /api/v1/).
+
+POST /api/v1/corpora/{id}/run         → crée un job par page du corpus
+POST /api/v1/pages/{id}/run           → crée un job pour une page
+GET  /api/v1/jobs/{job_id}            → état du job
+POST /api/v1/jobs/{job_id}/retry      → relance un job FAILED
+
+Règle : les jobs sont créés en BDD et retournent immédiatement.
+Le pipeline réel (analyzer) sera branché en Session C.
+"""
+# 1. stdlib
+import uuid
+from datetime import datetime, timezone
+
+# 2. third-party
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, ConfigDict
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+# 3. local
+from app.models.corpus import CorpusModel, PageModel
+from app.models.database import get_db
+from app.models.job import JobModel
+
+router = APIRouter(tags=["jobs"])
+
+_JOB_STATUS_PENDING = "pending"
+_JOB_STATUS_FAILED = "failed"
+
+
+# ── Schémas de réponse ────────────────────────────────────────────────────────
+
+class JobResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    corpus_id: str
+    page_id: str | None
+    status: str
+    started_at: datetime | None
+    finished_at: datetime | None
+    error_message: str | None
+    created_at: datetime
+
+
+class CorpusRunResponse(BaseModel):
+    corpus_id: str
+    jobs_created: int
+    job_ids: list[str]
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _new_job(corpus_id: str, page_id: str | None) -> JobModel:
+    now = datetime.now(timezone.utc)
+    return JobModel(
+        id=str(uuid.uuid4()),
+        corpus_id=corpus_id,
+        page_id=page_id,
+        status=_JOB_STATUS_PENDING,
+        started_at=None,
+        finished_at=None,
+        error_message=None,
+        created_at=now,
+    )
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+@router.post("/corpora/{corpus_id}/run", response_model=CorpusRunResponse, status_code=202)
+async def run_corpus(
+    corpus_id: str, db: AsyncSession = Depends(get_db)
+) -> CorpusRunResponse:
+    """Lance le pipeline sur toutes les pages du corpus.
+
+    Crée un JobModel par page (status=pending). Retourne immédiatement.
+    Le pipeline réel sera branché en Session C.
+    """
+    corpus = await db.get(CorpusModel, corpus_id)
+    if corpus is None:
+        raise HTTPException(status_code=404, detail="Corpus introuvable")
+
+    from app.models.corpus import ManuscriptModel
+    ms_result = await db.execute(
+        select(ManuscriptModel).where(ManuscriptModel.corpus_id == corpus_id)
+    )
+    ms_ids = [ms.id for ms in ms_result.scalars().all()]
+
+    pages_result = await db.execute(
+        select(PageModel).where(PageModel.manuscript_id.in_(ms_ids))
+    )
+    pages = list(pages_result.scalars().all())
+
+    jobs = [_new_job(corpus_id, page.id) for page in pages]
+    for job in jobs:
+        db.add(job)
+    await db.commit()
+
+    return CorpusRunResponse(
+        corpus_id=corpus_id,
+        jobs_created=len(jobs),
+        job_ids=[j.id for j in jobs],
+    )
+
+
+@router.post("/pages/{page_id}/run", response_model=JobResponse, status_code=202)
+async def run_page(
+    page_id: str, db: AsyncSession = Depends(get_db)
+) -> JobModel:
+    """Lance le pipeline sur une seule page. Retourne le job créé."""
+    page = await db.get(PageModel, page_id)
+    if page is None:
+        raise HTTPException(status_code=404, detail="Page introuvable")
+
+    from app.models.corpus import ManuscriptModel
+    manuscript = await db.get(ManuscriptModel, page.manuscript_id)
+    if manuscript is None:
+        raise HTTPException(status_code=404, detail="Manuscrit introuvable")
+
+    job = _new_job(manuscript.corpus_id, page_id)
+    db.add(job)
+    await db.commit()
+    await db.refresh(job)
+    return job
+
+
+@router.get("/jobs/{job_id}", response_model=JobResponse)
+async def get_job(job_id: str, db: AsyncSession = Depends(get_db)) -> JobModel:
+    """Retourne l'état d'un job."""
+    job = await db.get(JobModel, job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="Job introuvable")
+    return job
+
+
+@router.post("/jobs/{job_id}/retry", response_model=JobResponse)
+async def retry_job(job_id: str, db: AsyncSession = Depends(get_db)) -> JobModel:
+    """Relance un job en état FAILED (remet le status à pending).
+
+    Retourne 409 si le job n'est pas dans l'état FAILED.
+    """
+    job = await db.get(JobModel, job_id)
+    if job is None:
+        raise HTTPException(status_code=404, detail="Job introuvable")
+    if job.status != _JOB_STATUS_FAILED:
+        raise HTTPException(
+            status_code=409,
+            detail=f"Le job ne peut être relancé que depuis l'état 'failed' (statut actuel : '{job.status}')",
+        )
+    job.status = _JOB_STATUS_PENDING
+    job.error_message = None
+    job.started_at = None
+    job.finished_at = None
+    await db.commit()
+    await db.refresh(job)
+    return job

backend/app/api/v1/models_api.py

@@ -0,0 +1,173 @@
+"""
+Endpoints de gestion des modèles IA (R10 — préfixe /api/v1/).
+
+POST /api/v1/settings/api-key       → valide la clé sans la stocker (R06)
+GET  /api/v1/models                 → liste les modèles disponibles
+POST /api/v1/models/refresh         → force la mise à jour de la liste
+PUT  /api/v1/corpora/{id}/model     → associe un modèle à un corpus
+GET  /api/v1/corpora/{id}/model     → modèle actif d'un corpus
+
+Règle R06 : la clé API ne transite jamais vers la BDD — elle reste
+            exclusivement dans les variables d'environnement.
+"""
+# 1. stdlib
+import logging
+from datetime import datetime, timezone
+
+# 2. third-party
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel, ConfigDict
+from sqlalchemy.ext.asyncio import AsyncSession
+
+# 3. local
+from app.models.corpus import CorpusModel
+from app.models.database import get_db
+from app.models.model_config_db import ModelConfigDB
+from app.services.ai.model_registry import list_all_models
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=["models"])
+
+
+# ── Schémas ───────────────────────────────────────────────────────────────────
+
+class ApiKeyRequest(BaseModel):
+    api_key: str
+    provider_type: str = "google_ai_studio"
+
+
+class ApiKeyResponse(BaseModel):
+    valid: bool
+    provider: str
+    model_count: int
+    error: str | None = None
+
+
+class ModelSelectRequest(BaseModel):
+    model_id: str
+    provider_type: str
+    display_name: str = ""
+
+
+class ModelConfigResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    corpus_id: str
+    provider_type: str
+    selected_model_id: str
+    selected_model_display_name: str
+    updated_at: datetime
+
+
+class ModelsRefreshResponse(BaseModel):
+    models: list[dict]
+    count: int
+    refreshed_at: datetime
+
+
+# ── Validation de clé API (isolé pour les tests) ──────────────────────────────
+
+def _validate_api_key(api_key: str, provider_type: str) -> tuple[bool, int, str | None]:
+    """Essaie de lister les modèles avec la clé fournie.
+
+    Retourne (valid, model_count, error_message).
+    Fonction isolée au niveau module pour être patchable dans les tests.
+    """
+    try:
+        from google import genai  # import local pour éviter l'import top-level
+        client = genai.Client(api_key=api_key)
+        raw_models = list(client.models.list())
+        vision_count = sum(
+            1 for m in raw_models if "gemini" in (getattr(m, "name", "") or "").lower()
+        )
+        return True, vision_count, None
+    except Exception as exc:
+        return False, 0, str(exc)
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+@router.post("/settings/api-key", response_model=ApiKeyResponse)
+async def validate_api_key(body: ApiKeyRequest) -> ApiKeyResponse:
+    """Valide qu'une clé API fonctionne (appel list_models).
+
+    La clé N'EST PAS stockée (R06). Elle reste dans les variables d'env.
+    """
+    valid, count, error = _validate_api_key(body.api_key, body.provider_type)
+    return ApiKeyResponse(
+        valid=valid,
+        provider=body.provider_type,
+        model_count=count,
+        error=error,
+    )
+
+
+@router.get("/models", response_model=list[dict])
+async def get_models() -> list[dict]:
+    """Liste tous les modèles disponibles sur les providers configurés."""
+    models = list_all_models()
+    return [m.model_dump() for m in models]
+
+
+@router.post("/models/refresh", response_model=ModelsRefreshResponse)
+async def refresh_models() -> ModelsRefreshResponse:
+    """Force la mise à jour de la liste des modèles (vide le cache implicite)."""
+    models = list_all_models()
+    return ModelsRefreshResponse(
+        models=[m.model_dump() for m in models],
+        count=len(models),
+        refreshed_at=datetime.now(timezone.utc),
+    )
+
+
+@router.put("/corpora/{corpus_id}/model", response_model=ModelConfigResponse)
+async def set_corpus_model(
+    corpus_id: str,
+    body: ModelSelectRequest,
+    db: AsyncSession = Depends(get_db),
+) -> ModelConfigDB:
+    """Associe un modèle IA à un corpus. Crée ou met à jour la configuration."""
+    corpus = await db.get(CorpusModel, corpus_id)
+    if corpus is None:
+        raise HTTPException(status_code=404, detail="Corpus introuvable")
+
+    display_name = body.display_name or body.model_id
+
+    config = await db.get(ModelConfigDB, corpus_id)
+    if config is None:
+        config = ModelConfigDB(
+            corpus_id=corpus_id,
+            provider_type=body.provider_type,
+            selected_model_id=body.model_id,
+            selected_model_display_name=display_name,
+            updated_at=datetime.now(timezone.utc),
+        )
+        db.add(config)
+    else:
+        config.provider_type = body.provider_type
+        config.selected_model_id = body.model_id
+        config.selected_model_display_name = display_name
+        config.updated_at = datetime.now(timezone.utc)
+
+    await db.commit()
+    await db.refresh(config)
+    return config
+
+
+@router.get("/corpora/{corpus_id}/model", response_model=ModelConfigResponse)
+async def get_corpus_model(
+    corpus_id: str, db: AsyncSession = Depends(get_db)
+) -> ModelConfigDB:
+    """Retourne la configuration du modèle IA actif pour un corpus."""
+    corpus = await db.get(CorpusModel, corpus_id)
+    if corpus is None:
+        raise HTTPException(status_code=404, detail="Corpus introuvable")
+
+    config = await db.get(ModelConfigDB, corpus_id)
+    if config is None:
+        raise HTTPException(
+            status_code=404,
+            detail="Aucun modèle configuré pour ce corpus",
+        )
+    return config

backend/app/main.py

@@ -15,7 +15,7 @@ from fastapi.middleware.cors import CORSMiddleware
 
 # 3. local — on importe les modèles pour que Base.metadata les connaisse
 import app.models  # noqa: F401  (enregistrement des modèles SQLAlchemy)
-from app.api.v1 import corpora, export, pages, profiles
+from app.api.v1 import corpora, export, ingest, jobs, models_api, pages, profiles
 from app.models.database import Base, engine
 
 logger = logging.getLogger(__name__)
@@ -55,3 +55,6 @@ app.include_router(corpora.router, prefix=_V1_PREFIX)
 app.include_router(pages.router, prefix=_V1_PREFIX)
 app.include_router(export.router, prefix=_V1_PREFIX)
 app.include_router(profiles.router, prefix=_V1_PREFIX)
+app.include_router(jobs.router, prefix=_V1_PREFIX)
+app.include_router(ingest.router, prefix=_V1_PREFIX)
+app.include_router(models_api.router, prefix=_V1_PREFIX)

backend/app/models/__init__.py

@@ -3,5 +3,13 @@ Modèles SQLAlchemy — importés ici pour que Base.metadata les connaisse
 au moment de la création des tables (Base.metadata.create_all).
 """
 from app.models.corpus import CorpusModel, ManuscriptModel, PageModel
+from app.models.job import JobModel
+from app.models.model_config_db import ModelConfigDB
 
-__all__ = ["CorpusModel", "ManuscriptModel", "PageModel"]
+__all__ = [
+    "CorpusModel",
+    "ManuscriptModel",
+    "PageModel",
+    "JobModel",
+    "ModelConfigDB",
+]

backend/app/models/job.py

@@ -0,0 +1,40 @@
+"""
+Modèle SQLAlchemy 2.0 — table des jobs de traitement.
+
+Un job suit l'exécution du pipeline sur une page.
+  corpus.run  → crée un JobModel par page du corpus (page_id renseigné)
+  pages.run   → crée un JobModel pour la page cible
+
+Cycle de vie :
+  pending → running → done
+                   ↘ failed
+"""
+# 1. stdlib
+from datetime import datetime
+
+# 2. third-party
+from sqlalchemy import DateTime, ForeignKey, String, Text
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+# 3. local
+from app.models.database import Base
+
+
+class JobModel(Base):
+    """Suivi d'un job de pipeline (1 job = 1 page)."""
+
+    __tablename__ = "jobs"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True)
+    corpus_id: Mapped[str] = mapped_column(
+        String, ForeignKey("corpora.id"), nullable=False, index=True
+    )
+    page_id: Mapped[str | None] = mapped_column(
+        String, ForeignKey("pages.id"), nullable=True, index=True
+    )
+    # pending / running / done / failed
+    status: Mapped[str] = mapped_column(String, nullable=False, default="pending")
+    started_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    finished_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
+    error_message: Mapped[str | None] = mapped_column(Text, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)

backend/app/models/model_config_db.py

@@ -0,0 +1,29 @@
+"""
+Modèle SQLAlchemy 2.0 — configuration du modèle IA par corpus.
+
+Une seule ligne par corpus (corpus_id = PK).
+La clé API n'est JAMAIS stockée ici (R06) — elle reste dans l'environnement.
+"""
+# 1. stdlib
+from datetime import datetime
+
+# 2. third-party
+from sqlalchemy import DateTime, ForeignKey, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+# 3. local
+from app.models.database import Base
+
+
+class ModelConfigDB(Base):
+    """Modèle IA sélectionné pour un corpus (1 entrée par corpus)."""
+
+    __tablename__ = "model_configs"
+
+    corpus_id: Mapped[str] = mapped_column(
+        String, ForeignKey("corpora.id"), primary_key=True
+    )
+    provider_type: Mapped[str] = mapped_column(String, nullable=False)
+    selected_model_id: Mapped[str] = mapped_column(String, nullable=False)
+    selected_model_display_name: Mapped[str] = mapped_column(String, nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)

backend/pyproject.toml

@@ -18,6 +18,7 @@ dependencies = [
     "httpx>=0.27",
     "lxml>=5.2",
     "Pillow>=10.3",
+    "python-multipart>=0.0.9",
 ]
 
 [project.optional-dependencies]

backend/tests/test_api_ingest.py

@@ -0,0 +1,419 @@
+"""
+Tests des endpoints d'ingestion /api/v1/corpora/{id}/ingest/* (Sprint 4 — Session B).
+
+Stratégie :
+  - BDD SQLite en mémoire
+  - Appels réseau mockés via monkeypatch (_fetch_json_manifest)
+  - Écriture disque mockée via monkeypatch (Path.mkdir, Path.write_bytes)
+
+Vérifie :
+- POST /ingest/files → pages créées, IDs retournés
+- POST /ingest/iiif-manifest → manifest parsé, pages créées
+- POST /ingest/iiif-images → pages créées depuis liste d'URLs
+- 404 si corpus inexistant
+- 422 si données invalides
+"""
+# 1. stdlib
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from unittest.mock import AsyncMock, patch
+
+# 2. third-party
+import pytest
+
+# 3. local
+import app.api.v1.ingest as ingest_module
+from app.models.corpus import CorpusModel
+from tests.conftest_api import async_client, db_session  # noqa: F401
+
+_NOW = datetime.now(timezone.utc)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+async def _make_corpus(db, slug="test-ingest"):
+    corpus = CorpusModel(
+        id=str(uuid.uuid4()), slug=slug, title="Corpus Test",
+        profile_id="medieval-illuminated", created_at=_NOW, updated_at=_NOW,
+    )
+    db.add(corpus)
+    await db.commit()
+    await db.refresh(corpus)
+    return corpus
+
+
+def _iiif3_manifest(n_canvases: int = 3) -> dict:
+    """Génère un manifest IIIF 3.0 minimal avec n canvases."""
+    return {
+        "@context": "http://iiif.io/api/presentation/3/context.json",
+        "id": "https://example.com/manifest",
+        "type": "Manifest",
+        "label": {"fr": ["Beatus de Saint-Sever"]},
+        "items": [
+            {
+                "id": f"https://example.com/canvas/{i}",
+                "type": "Canvas",
+                "label": {"none": [f"f{i:03d}r"]},
+                "width": 1500, "height": 2000,
+                "items": [
+                    {
+                        "id": f"https://example.com/canvas/{i}/page",
+                        "type": "AnnotationPage",
+                        "items": [
+                            {
+                                "id": f"https://example.com/canvas/{i}/annotation",
+                                "type": "Annotation",
+                                "motivation": "painting",
+                                "body": {
+                                    "id": f"https://example.com/images/{i}.jpg",
+                                    "type": "Image",
+                                    "format": "image/jpeg",
+                                },
+                                "target": f"https://example.com/canvas/{i}",
+                            }
+                        ],
+                    }
+                ],
+            }
+            for i in range(1, n_canvases + 1)
+        ],
+    }
+
+
+def _iiif2_manifest(n_canvases: int = 2) -> dict:
+    """Génère un manifest IIIF 2.x minimal."""
+    return {
+        "@context": "http://iiif.io/api/presentation/2/context.json",
+        "@type": "sc:Manifest",
+        "label": "Test Manuscript 2.x",
+        "sequences": [
+            {
+                "canvases": [
+                    {
+                        "@id": f"https://example.com/canvas/{i}",
+                        "@type": "sc:Canvas",
+                        "label": f"f{i:03d}r",
+                        "images": [
+                            {
+                                "resource": {
+                                    "@id": f"https://example.com/images/{i}.jpg"
+                                }
+                            }
+                        ],
+                    }
+                    for i in range(1, n_canvases + 1)
+                ]
+            }
+        ],
+    }
+
+
+# ---------------------------------------------------------------------------
+# POST /api/v1/corpora/{id}/ingest/files
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_ingest_files_corpus_not_found(async_client):
+    response = await async_client.post(
+        "/api/v1/corpora/nonexistent/ingest/files",
+        files=[("files", ("img.jpg", b"data", "image/jpeg"))],
+    )
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_ingest_files_ok(async_client, db_session, tmp_path, monkeypatch):
+    corpus = await _make_corpus(db_session)
+    monkeypatch.setattr(_config_module := __import__("app.config", fromlist=["config"]), "settings",
+                        type("S", (), {"data_dir": tmp_path})())
+
+    import app.config as _cfg
+    import app.api.v1.ingest as _ingest
+    original_data_dir = _cfg.settings.data_dir
+    _cfg.settings.data_dir = tmp_path
+
+    try:
+        response = await async_client.post(
+            f"/api/v1/corpora/{corpus.id}/ingest/files",
+            files=[
+                ("files", ("f001r.jpg", b"fake_jpeg_data_1", "image/jpeg")),
+                ("files", ("f002r.jpg", b"fake_jpeg_data_2", "image/jpeg")),
+            ],
+        )
+        assert response.status_code == 201
+        data = response.json()
+        assert data["pages_created"] == 2
+        assert len(data["page_ids"]) == 2
+        assert data["corpus_id"] == corpus.id
+    finally:
+        _cfg.settings.data_dir = original_data_dir
+
+
+@pytest.mark.asyncio
+async def test_ingest_files_creates_manuscript(async_client, db_session, tmp_path):
+    corpus = await _make_corpus(db_session)
+
+    import app.config as _cfg
+    original = _cfg.settings.data_dir
+    _cfg.settings.data_dir = tmp_path
+    try:
+        response = await async_client.post(
+            f"/api/v1/corpora/{corpus.id}/ingest/files",
+            files=[("files", ("f001r.jpg", b"data", "image/jpeg"))],
+        )
+        data = response.json()
+        assert "manuscript_id" in data
+        assert data["manuscript_id"]  # non-vide
+    finally:
+        _cfg.settings.data_dir = original
+
+
+@pytest.mark.asyncio
+async def test_ingest_files_folio_from_filename(async_client, db_session, tmp_path):
+    """Le folio_label est dérivé du nom de fichier (sans extension)."""
+    corpus = await _make_corpus(db_session)
+
+    import app.config as _cfg
+    original = _cfg.settings.data_dir
+    _cfg.settings.data_dir = tmp_path
+    try:
+        response = await async_client.post(
+            f"/api/v1/corpora/{corpus.id}/ingest/files",
+            files=[("files", ("f013v.jpg", b"data", "image/jpeg"))],
+        )
+        data = response.json()
+        # L'ID de page contient le folio_label
+        assert any("f013v" in pid for pid in data["page_ids"])
+    finally:
+        _cfg.settings.data_dir = original
+
+
+@pytest.mark.asyncio
+async def test_ingest_files_writes_to_disk(async_client, db_session, tmp_path):
+    """Les fichiers sont bien écrits dans data/corpora/{slug}/masters/."""
+    corpus = await _make_corpus(db_session, slug="test-write")
+
+    import app.config as _cfg
+    original = _cfg.settings.data_dir
+    _cfg.settings.data_dir = tmp_path
+    try:
+        await async_client.post(
+            f"/api/v1/corpora/{corpus.id}/ingest/files",
+            files=[("files", ("f001r.jpg", b"JPEG_CONTENT", "image/jpeg"))],
+        )
+        expected = tmp_path / "corpora" / "test-write" / "masters" / "f001r" / "f001r.jpg"
+        assert expected.exists()
+        assert expected.read_bytes() == b"JPEG_CONTENT"
+    finally:
+        _cfg.settings.data_dir = original
+
+
+# ---------------------------------------------------------------------------
+# POST /api/v1/corpora/{id}/ingest/iiif-manifest
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_ingest_manifest_corpus_not_found(async_client):
+    response = await async_client.post(
+        "/api/v1/corpora/nonexistent/ingest/iiif-manifest",
+        json={"manifest_url": "https://example.com/manifest"},
+    )
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_ingest_manifest_iiif3_ok(async_client, db_session, monkeypatch):
+    corpus = await _make_corpus(db_session)
+    manifest = _iiif3_manifest(n_canvases=3)
+
+    async def fake_fetch(url: str) -> dict:
+        return manifest
+
+    monkeypatch.setattr(ingest_module, "_fetch_json_manifest", fake_fetch)
+
+    response = await async_client.post(
+        f"/api/v1/corpora/{corpus.id}/ingest/iiif-manifest",
+        json={"manifest_url": "https://example.com/manifest"},
+    )
+    assert response.status_code == 201
+    data = response.json()
+    assert data["pages_created"] == 3
+    assert len(data["page_ids"]) == 3
+
+
+@pytest.mark.asyncio
+async def test_ingest_manifest_iiif2_ok(async_client, db_session, monkeypatch):
+    corpus = await _make_corpus(db_session)
+    manifest = _iiif2_manifest(n_canvases=2)
+
+    async def fake_fetch(url: str) -> dict:
+        return manifest
+
+    monkeypatch.setattr(ingest_module, "_fetch_json_manifest", fake_fetch)
+
+    response = await async_client.post(
+        f"/api/v1/corpora/{corpus.id}/ingest/iiif-manifest",
+        json={"manifest_url": "https://example.com/manifest"},
+    )
+    assert response.status_code == 201
+    assert response.json()["pages_created"] == 2
+
+
+@pytest.mark.asyncio
+async def test_ingest_manifest_extracts_folio_labels(async_client, db_session, monkeypatch):
+    """Les folio_labels sont extraits des labels des canvases."""
+    corpus = await _make_corpus(db_session)
+    manifest = _iiif3_manifest(n_canvases=2)
+
+    async def fake_fetch(url: str) -> dict:
+        return manifest
+
+    monkeypatch.setattr(ingest_module, "_fetch_json_manifest", fake_fetch)
+
+    data = (await async_client.post(
+        f"/api/v1/corpora/{corpus.id}/ingest/iiif-manifest",
+        json={"manifest_url": "https://example.com/manifest"},
+    )).json()
+
+    # Canvas labels: "f001r", "f002r"
+    assert any("f001r" in pid for pid in data["page_ids"])
+    assert any("f002r" in pid for pid in data["page_ids"])
+
+
+@pytest.mark.asyncio
+async def test_ingest_manifest_empty_canvases_422(async_client, db_session, monkeypatch):
+    """Manifest sans canvases → 422."""
+    corpus = await _make_corpus(db_session)
+
+    async def fake_fetch(url: str) -> dict:
+        return {"type": "Manifest", "items": []}
+
+    monkeypatch.setattr(ingest_module, "_fetch_json_manifest", fake_fetch)
+
+    response = await async_client.post(
+        f"/api/v1/corpora/{corpus.id}/ingest/iiif-manifest",
+        json={"manifest_url": "https://example.com/manifest"},
+    )
+    assert response.status_code == 422
+
+
+@pytest.mark.asyncio
+async def test_ingest_manifest_network_error_502(async_client, db_session, monkeypatch):
+    """Erreur réseau → 502."""
+    corpus = await _make_corpus(db_session)
+    import httpx
+
+    async def fake_fetch(url: str) -> dict:
+        raise httpx.RequestError("Connection refused")
+
+    monkeypatch.setattr(ingest_module, "_fetch_json_manifest", fake_fetch)
+
+    response = await async_client.post(
+        f"/api/v1/corpora/{corpus.id}/ingest/iiif-manifest",
+        json={"manifest_url": "https://example.com/manifest"},
+    )
+    assert response.status_code == 502
+
+
+@pytest.mark.asyncio
+async def test_ingest_manifest_returns_corpus_id(async_client, db_session, monkeypatch):
+    corpus = await _make_corpus(db_session)
+    monkeypatch.setattr(ingest_module, "_fetch_json_manifest", AsyncMock(return_value=_iiif3_manifest(1)))
+
+    data = (await async_client.post(
+        f"/api/v1/corpora/{corpus.id}/ingest/iiif-manifest",
+        json={"manifest_url": "https://example.com/manifest"},
+    )).json()
+    assert data["corpus_id"] == corpus.id
+
+
+# ---------------------------------------------------------------------------
+# POST /api/v1/corpora/{id}/ingest/iiif-images
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_ingest_images_corpus_not_found(async_client):
+    response = await async_client.post(
+        "/api/v1/corpora/nonexistent/ingest/iiif-images",
+        json={"urls": ["https://x.com/1.jpg"], "folio_labels": ["f001r"]},
+    )
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_ingest_images_ok(async_client, db_session):
+    corpus = await _make_corpus(db_session)
+    urls = ["https://example.com/img1.jpg", "https://example.com/img2.jpg"]
+    labels = ["f001r", "f002r"]
+
+    response = await async_client.post(
+        f"/api/v1/corpora/{corpus.id}/ingest/iiif-images",
+        json={"urls": urls, "folio_labels": labels},
+    )
+    assert response.status_code == 201
+    data = response.json()
+    assert data["pages_created"] == 2
+    assert len(data["page_ids"]) == 2
+
+
+@pytest.mark.asyncio
+async def test_ingest_images_folio_labels_in_ids(async_client, db_session):
+    corpus = await _make_corpus(db_session)
+    response = await async_client.post(
+        f"/api/v1/corpora/{corpus.id}/ingest/iiif-images",
+        json={
+            "urls": ["https://example.com/a.jpg"],
+            "folio_labels": ["f013v"],
+        },
+    )
+    data = response.json()
+    assert any("f013v" in pid for pid in data["page_ids"])
+
+
+@pytest.mark.asyncio
+async def test_ingest_images_mismatched_lengths_422(async_client, db_session):
+    """urls et folio_labels de longueurs différentes → 422."""
+    corpus = await _make_corpus(db_session)
+    response = await async_client.post(
+        f"/api/v1/corpora/{corpus.id}/ingest/iiif-images",
+        json={"urls": ["https://a.com/1.jpg", "https://a.com/2.jpg"], "folio_labels": ["f001r"]},
+    )
+    assert response.status_code == 422
+
+
+@pytest.mark.asyncio
+async def test_ingest_images_empty_urls_422(async_client, db_session):
+    corpus = await _make_corpus(db_session)
+    response = await async_client.post(
+        f"/api/v1/corpora/{corpus.id}/ingest/iiif-images",
+        json={"urls": [], "folio_labels": []},
+    )
+    assert response.status_code == 422
+
+
+@pytest.mark.asyncio
+async def test_ingest_images_pages_in_sequence_order(async_client, db_session):
+    """Les pages ont des séquences consécutives."""
+    corpus = await _make_corpus(db_session)
+    n = 4
+    urls = [f"https://example.com/{i}.jpg" for i in range(1, n + 1)]
+    labels = [f"f{i:03d}r" for i in range(1, n + 1)]
+
+    data = (await async_client.post(
+        f"/api/v1/corpora/{corpus.id}/ingest/iiif-images",
+        json={"urls": urls, "folio_labels": labels},
+    )).json()
+    assert data["pages_created"] == n
+
+
+@pytest.mark.asyncio
+async def test_ingest_images_corpus_id_in_response(async_client, db_session):
+    corpus = await _make_corpus(db_session)
+    data = (await async_client.post(
+        f"/api/v1/corpora/{corpus.id}/ingest/iiif-images",
+        json={"urls": ["https://x.com/1.jpg"], "folio_labels": ["f001r"]},
+    )).json()
+    assert data["corpus_id"] == corpus.id

backend/tests/test_api_jobs.py

@@ -0,0 +1,289 @@
+"""
+Tests des endpoints /api/v1/jobs et /api/v1/corpora/{id}/run (Sprint 4 — Session B).
+
+Vérifie :
+- POST /api/v1/corpora/{id}/run → 202 + jobs_created + job_ids
+- POST /api/v1/pages/{id}/run   → 202 + job unique
+- GET  /api/v1/jobs/{job_id}    → 200 ou 404
+- POST /api/v1/jobs/{job_id}/retry → 200 (FAILED) ou 409 (autre statut)
+- Isolation : corpus/page inexistants → 404
+"""
+# 1. stdlib
+import uuid
+from datetime import datetime, timezone
+
+# 2. third-party
+import pytest
+
+# 3. local
+from app.models.corpus import CorpusModel, ManuscriptModel, PageModel
+from app.models.job import JobModel
+from tests.conftest_api import async_client, db_session  # noqa: F401
+
+_NOW = datetime.now(timezone.utc)
+
+
+# ---------------------------------------------------------------------------
+# Helpers — création de données de test
+# ---------------------------------------------------------------------------
+
+async def _make_corpus(db, slug="test-c"):
+    corpus = CorpusModel(
+        id=str(uuid.uuid4()), slug=slug, title="Test", profile_id="medieval-illuminated",
+        created_at=_NOW, updated_at=_NOW,
+    )
+    db.add(corpus)
+    await db.commit()
+    await db.refresh(corpus)
+    return corpus
+
+
+async def _make_manuscript(db, corpus_id):
+    ms = ManuscriptModel(
+        id=str(uuid.uuid4()), corpus_id=corpus_id, title="MS", total_pages=0,
+    )
+    db.add(ms)
+    await db.commit()
+    await db.refresh(ms)
+    return ms
+
+
+async def _make_page(db, ms_id, folio="f001r", seq=1):
+    page = PageModel(
+        id=str(uuid.uuid4()), manuscript_id=ms_id, folio_label=folio,
+        sequence=seq, processing_status="INGESTED",
+    )
+    db.add(page)
+    await db.commit()
+    await db.refresh(page)
+    return page
+
+
+async def _make_failed_job(db, corpus_id, page_id=None):
+    """Crée un job en état FAILED pour tester retry."""
+    job = JobModel(
+        id=str(uuid.uuid4()),
+        corpus_id=corpus_id,
+        page_id=page_id,
+        status="failed",
+        error_message="Simulated failure",
+        created_at=_NOW,
+    )
+    db.add(job)
+    await db.commit()
+    await db.refresh(job)
+    return job
+
+
+# ---------------------------------------------------------------------------
+# POST /api/v1/corpora/{id}/run
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_run_corpus_not_found(async_client):
+    response = await async_client.post("/api/v1/corpora/nonexistent/run")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_run_corpus_no_pages(async_client, db_session):
+    """Corpus sans pages → 202, jobs_created = 0."""
+    corpus = await _make_corpus(db_session)
+    response = await async_client.post(f"/api/v1/corpora/{corpus.id}/run")
+    assert response.status_code == 202
+    data = response.json()
+    assert data["jobs_created"] == 0
+    assert data["job_ids"] == []
+    assert data["corpus_id"] == corpus.id
+
+
+@pytest.mark.asyncio
+async def test_run_corpus_creates_jobs_per_page(async_client, db_session):
+    """Corpus avec 3 pages → 3 jobs créés."""
+    corpus = await _make_corpus(db_session)
+    ms = await _make_manuscript(db_session, corpus.id)
+    for i in range(3):
+        await _make_page(db_session, ms.id, folio=f"f{i+1:03d}r", seq=i + 1)
+
+    response = await async_client.post(f"/api/v1/corpora/{corpus.id}/run")
+    assert response.status_code == 202
+    data = response.json()
+    assert data["jobs_created"] == 3
+    assert len(data["job_ids"]) == 3
+
+
+@pytest.mark.asyncio
+async def test_run_corpus_job_ids_are_unique(async_client, db_session):
+    corpus = await _make_corpus(db_session)
+    ms = await _make_manuscript(db_session, corpus.id)
+    for i in range(2):
+        await _make_page(db_session, ms.id, folio=f"f{i+1:03d}r", seq=i + 1)
+
+    data = (await async_client.post(f"/api/v1/corpora/{corpus.id}/run")).json()
+    assert len(set(data["job_ids"])) == 2  # all unique
+
+
+@pytest.mark.asyncio
+async def test_run_corpus_jobs_are_pending(async_client, db_session):
+    """Les jobs créés par corpus.run ont le statut 'pending'."""
+    corpus = await _make_corpus(db_session)
+    ms = await _make_manuscript(db_session, corpus.id)
+    await _make_page(db_session, ms.id)
+
+    run_data = (await async_client.post(f"/api/v1/corpora/{corpus.id}/run")).json()
+    job_id = run_data["job_ids"][0]
+
+    job_data = (await async_client.get(f"/api/v1/jobs/{job_id}")).json()
+    assert job_data["status"] == "pending"
+
+
+# ---------------------------------------------------------------------------
+# POST /api/v1/pages/{id}/run
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_run_page_not_found(async_client):
+    response = await async_client.post("/api/v1/pages/nonexistent/run")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_run_page_creates_job(async_client, db_session):
+    corpus = await _make_corpus(db_session)
+    ms = await _make_manuscript(db_session, corpus.id)
+    page = await _make_page(db_session, ms.id)
+
+    response = await async_client.post(f"/api/v1/pages/{page.id}/run")
+    assert response.status_code == 202
+
+
+@pytest.mark.asyncio
+async def test_run_page_job_fields(async_client, db_session):
+    corpus = await _make_corpus(db_session)
+    ms = await _make_manuscript(db_session, corpus.id)
+    page = await _make_page(db_session, ms.id)
+
+    data = (await async_client.post(f"/api/v1/pages/{page.id}/run")).json()
+    assert data["page_id"] == page.id
+    assert data["corpus_id"] == corpus.id
+    assert data["status"] == "pending"
+    assert data["started_at"] is None
+    assert data["finished_at"] is None
+    assert data["error_message"] is None
+
+
+@pytest.mark.asyncio
+async def test_run_page_job_id_is_uuid(async_client, db_session):
+    corpus = await _make_corpus(db_session)
+    ms = await _make_manuscript(db_session, corpus.id)
+    page = await _make_page(db_session, ms.id)
+
+    data = (await async_client.post(f"/api/v1/pages/{page.id}/run")).json()
+    assert len(data["id"]) == 36
+
+
+@pytest.mark.asyncio
+async def test_run_page_multiple_times_creates_multiple_jobs(async_client, db_session):
+    """Lancer run sur la même page deux fois crée deux jobs distincts."""
+    corpus = await _make_corpus(db_session)
+    ms = await _make_manuscript(db_session, corpus.id)
+    page = await _make_page(db_session, ms.id)
+
+    r1 = (await async_client.post(f"/api/v1/pages/{page.id}/run")).json()
+    r2 = (await async_client.post(f"/api/v1/pages/{page.id}/run")).json()
+    assert r1["id"] != r2["id"]
+
+
+# ---------------------------------------------------------------------------
+# GET /api/v1/jobs/{job_id}
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_get_job_not_found(async_client):
+    response = await async_client.get("/api/v1/jobs/nonexistent")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_get_job_ok(async_client, db_session):
+    corpus = await _make_corpus(db_session)
+    ms = await _make_manuscript(db_session, corpus.id)
+    page = await _make_page(db_session, ms.id)
+
+    run_data = (await async_client.post(f"/api/v1/pages/{page.id}/run")).json()
+    job_id = run_data["id"]
+
+    response = await async_client.get(f"/api/v1/jobs/{job_id}")
+    assert response.status_code == 200
+    assert response.json()["id"] == job_id
+
+
+@pytest.mark.asyncio
+async def test_get_job_fields(async_client, db_session):
+    corpus = await _make_corpus(db_session)
+    ms = await _make_manuscript(db_session, corpus.id)
+    page = await _make_page(db_session, ms.id)
+
+    run_data = (await async_client.post(f"/api/v1/pages/{page.id}/run")).json()
+    data = (await async_client.get(f"/api/v1/jobs/{run_data['id']}")).json()
+
+    assert "status" in data
+    assert "corpus_id" in data
+    assert "page_id" in data
+    assert "created_at" in data
+
+
+# ---------------------------------------------------------------------------
+# POST /api/v1/jobs/{job_id}/retry
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_retry_job_not_found(async_client):
+    response = await async_client.post("/api/v1/jobs/nonexistent/retry")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_retry_pending_job_409(async_client, db_session):
+    """Un job en état 'pending' ne peut pas être relancé."""
+    corpus = await _make_corpus(db_session)
+    ms = await _make_manuscript(db_session, corpus.id)
+    page = await _make_page(db_session, ms.id)
+
+    job_data = (await async_client.post(f"/api/v1/pages/{page.id}/run")).json()
+    response = await async_client.post(f"/api/v1/jobs/{job_data['id']}/retry")
+    assert response.status_code == 409
+
+
+@pytest.mark.asyncio
+async def test_retry_failed_job_ok(async_client, db_session):
+    """Un job en état 'failed' peut être relancé → status passe à 'pending'."""
+    corpus = await _make_corpus(db_session)
+    job = await _make_failed_job(db_session, corpus.id)
+
+    response = await async_client.post(f"/api/v1/jobs/{job.id}/retry")
+    assert response.status_code == 200
+    data = response.json()
+    assert data["status"] == "pending"
+
+
+@pytest.mark.asyncio
+async def test_retry_failed_job_clears_error(async_client, db_session):
+    corpus = await _make_corpus(db_session)
+    job = await _make_failed_job(db_session, corpus.id)
+
+    data = (await async_client.post(f"/api/v1/jobs/{job.id}/retry")).json()
+    assert data["error_message"] is None
+    assert data["started_at"] is None
+    assert data["finished_at"] is None
+
+
+@pytest.mark.asyncio
+async def test_retry_failed_job_is_retrievable(async_client, db_session):
+    """Après retry, GET /jobs/{id} reflète le nouveau statut."""
+    corpus = await _make_corpus(db_session)
+    job = await _make_failed_job(db_session, corpus.id)
+
+    await async_client.post(f"/api/v1/jobs/{job.id}/retry")
+    data = (await async_client.get(f"/api/v1/jobs/{job.id}")).json()
+    assert data["status"] == "pending"

backend/tests/test_api_models.py

@@ -0,0 +1,365 @@
+"""
+Tests des endpoints /api/v1/models et /api/v1/settings/api-key (Sprint 4 — Session B).
+
+Stratégie :
+  - Appels Google AI mockés via monkeypatch sur _validate_api_key et list_all_models
+  - BDD SQLite en mémoire pour les endpoints qui touchent la BDD (PUT/GET model)
+
+Vérifie :
+- POST /api/v1/settings/api-key → valid/invalid
+- GET  /api/v1/models            → liste mockée
+- POST /api/v1/models/refresh    → mise à jour + timestamp
+- PUT  /api/v1/corpora/{id}/model → création + mise à jour
+- GET  /api/v1/corpora/{id}/model → 200 ou 404
+"""
+# 1. stdlib
+import uuid
+from datetime import datetime, timezone
+
+# 2. third-party
+import pytest
+
+# 3. local
+import app.api.v1.models_api as models_api_module
+from app.models.corpus import CorpusModel
+from app.schemas.model_config import ModelInfo, ProviderType
+from tests.conftest_api import async_client, db_session  # noqa: F401
+
+_NOW = datetime.now(timezone.utc)
+
+_MOCK_MODELS = [
+    ModelInfo(
+        model_id="gemini-2.0-flash",
+        display_name="Gemini 2.0 Flash",
+        provider=ProviderType.GOOGLE_AI_STUDIO,
+        supports_vision=True,
+        input_token_limit=1_000_000,
+        output_token_limit=8192,
+    ),
+    ModelInfo(
+        model_id="gemini-1.5-pro",
+        display_name="Gemini 1.5 Pro",
+        provider=ProviderType.GOOGLE_AI_STUDIO,
+        supports_vision=True,
+        input_token_limit=2_000_000,
+        output_token_limit=8192,
+    ),
+]
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+async def _make_corpus(db, slug="models-test"):
+    corpus = CorpusModel(
+        id=str(uuid.uuid4()), slug=slug, title="Models Test",
+        profile_id="medieval-illuminated", created_at=_NOW, updated_at=_NOW,
+    )
+    db.add(corpus)
+    await db.commit()
+    await db.refresh(corpus)
+    return corpus
+
+
+# ---------------------------------------------------------------------------
+# POST /api/v1/settings/api-key
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_api_key_valid(async_client, monkeypatch):
+    monkeypatch.setattr(
+        models_api_module, "_validate_api_key",
+        lambda key, provider: (True, 3, None),
+    )
+    response = await async_client.post(
+        "/api/v1/settings/api-key",
+        json={"api_key": "AIza-test-key", "provider_type": "google_ai_studio"},
+    )
+    assert response.status_code == 200
+    data = response.json()
+    assert data["valid"] is True
+    assert data["model_count"] == 3
+    assert data["provider"] == "google_ai_studio"
+    assert data["error"] is None
+
+
+@pytest.mark.asyncio
+async def test_api_key_invalid(async_client, monkeypatch):
+    monkeypatch.setattr(
+        models_api_module, "_validate_api_key",
+        lambda key, provider: (False, 0, "API key not valid"),
+    )
+    response = await async_client.post(
+        "/api/v1/settings/api-key",
+        json={"api_key": "bad-key", "provider_type": "google_ai_studio"},
+    )
+    assert response.status_code == 200
+    data = response.json()
+    assert data["valid"] is False
+    assert data["model_count"] == 0
+    assert data["error"] is not None
+
+
+@pytest.mark.asyncio
+async def test_api_key_not_stored_in_db(async_client, db_session, monkeypatch):
+    """La clé ne doit apparaître nulle part dans la BDD (R06)."""
+    monkeypatch.setattr(
+        models_api_module, "_validate_api_key",
+        lambda key, provider: (True, 2, None),
+    )
+    await async_client.post(
+        "/api/v1/settings/api-key",
+        json={"api_key": "secret-key-AIza123", "provider_type": "google_ai_studio"},
+    )
+    # Vérifie que la clé n'est pas dans model_configs
+    from sqlalchemy import text
+    result = await db_session.execute(text("SELECT * FROM model_configs"))
+    rows = result.fetchall()
+    for row in rows:
+        row_str = str(row)
+        assert "secret-key-AIza123" not in row_str
+
+
+@pytest.mark.asyncio
+async def test_api_key_missing_body_422(async_client):
+    response = await async_client.post("/api/v1/settings/api-key", json={})
+    assert response.status_code == 422
+
+
+@pytest.mark.asyncio
+async def test_api_key_default_provider_type(async_client, monkeypatch):
+    """provider_type est optionnel (default: google_ai_studio)."""
+    monkeypatch.setattr(
+        models_api_module, "_validate_api_key",
+        lambda key, provider: (True, 1, None),
+    )
+    response = await async_client.post(
+        "/api/v1/settings/api-key",
+        json={"api_key": "AIza-test"},
+    )
+    assert response.status_code == 200
+    assert response.json()["provider"] == "google_ai_studio"
+
+
+# ---------------------------------------------------------------------------
+# GET /api/v1/models
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_get_models_returns_list(async_client, monkeypatch):
+    monkeypatch.setattr(
+        models_api_module, "list_all_models", lambda: _MOCK_MODELS
+    )
+    response = await async_client.get("/api/v1/models")
+    assert response.status_code == 200
+    assert isinstance(response.json(), list)
+
+
+@pytest.mark.asyncio
+async def test_get_models_count(async_client, monkeypatch):
+    monkeypatch.setattr(
+        models_api_module, "list_all_models", lambda: _MOCK_MODELS
+    )
+    models = response = await async_client.get("/api/v1/models")
+    assert len(response.json()) == 2
+
+
+@pytest.mark.asyncio
+async def test_get_models_fields(async_client, monkeypatch):
+    monkeypatch.setattr(
+        models_api_module, "list_all_models", lambda: _MOCK_MODELS
+    )
+    models = (await async_client.get("/api/v1/models")).json()
+    m = models[0]
+    assert "model_id" in m
+    assert "display_name" in m
+    assert "provider" in m
+    assert "supports_vision" in m
+
+
+@pytest.mark.asyncio
+async def test_get_models_empty_when_no_provider(async_client, monkeypatch):
+    monkeypatch.setattr(models_api_module, "list_all_models", lambda: [])
+    response = await async_client.get("/api/v1/models")
+    assert response.status_code == 200
+    assert response.json() == []
+
+
+@pytest.mark.asyncio
+async def test_get_models_contains_gemini(async_client, monkeypatch):
+    monkeypatch.setattr(
+        models_api_module, "list_all_models", lambda: _MOCK_MODELS
+    )
+    models = (await async_client.get("/api/v1/models")).json()
+    ids = [m["model_id"] for m in models]
+    assert any("gemini" in mid for mid in ids)
+
+
+# ---------------------------------------------------------------------------
+# POST /api/v1/models/refresh
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_refresh_models_ok(async_client, monkeypatch):
+    monkeypatch.setattr(
+        models_api_module, "list_all_models", lambda: _MOCK_MODELS
+    )
+    response = await async_client.post("/api/v1/models/refresh")
+    assert response.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_refresh_models_has_timestamp(async_client, monkeypatch):
+    monkeypatch.setattr(
+        models_api_module, "list_all_models", lambda: _MOCK_MODELS
+    )
+    data = (await async_client.post("/api/v1/models/refresh")).json()
+    assert "refreshed_at" in data
+    assert data["refreshed_at"]  # non-vide
+
+
+@pytest.mark.asyncio
+async def test_refresh_models_count(async_client, monkeypatch):
+    monkeypatch.setattr(
+        models_api_module, "list_all_models", lambda: _MOCK_MODELS
+    )
+    data = (await async_client.post("/api/v1/models/refresh")).json()
+    assert data["count"] == 2
+    assert len(data["models"]) == 2
+
+
+@pytest.mark.asyncio
+async def test_refresh_models_structure(async_client, monkeypatch):
+    monkeypatch.setattr(
+        models_api_module, "list_all_models", lambda: _MOCK_MODELS
+    )
+    data = (await async_client.post("/api/v1/models/refresh")).json()
+    assert "models" in data
+    assert "count" in data
+    assert "refreshed_at" in data
+
+
+# ---------------------------------------------------------------------------
+# PUT /api/v1/corpora/{id}/model
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_set_model_corpus_not_found(async_client):
+    response = await async_client.put(
+        "/api/v1/corpora/nonexistent/model",
+        json={"model_id": "gemini-2.0-flash", "provider_type": "google_ai_studio"},
+    )
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_set_model_ok(async_client, db_session):
+    corpus = await _make_corpus(db_session)
+    response = await async_client.put(
+        f"/api/v1/corpora/{corpus.id}/model",
+        json={
+            "model_id": "gemini-2.0-flash",
+            "provider_type": "google_ai_studio",
+            "display_name": "Gemini 2.0 Flash",
+        },
+    )
+    assert response.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_set_model_response_fields(async_client, db_session):
+    corpus = await _make_corpus(db_session)
+    data = (await async_client.put(
+        f"/api/v1/corpora/{corpus.id}/model",
+        json={"model_id": "gemini-2.0-flash", "provider_type": "google_ai_studio"},
+    )).json()
+
+    assert data["corpus_id"] == corpus.id
+    assert data["selected_model_id"] == "gemini-2.0-flash"
+    assert data["provider_type"] == "google_ai_studio"
+    assert "updated_at" in data
+
+
+@pytest.mark.asyncio
+async def test_set_model_update_existing(async_client, db_session):
+    """PUT sur un corpus déjà configuré → mise à jour (pas de doublon)."""
+    corpus = await _make_corpus(db_session)
+
+    await async_client.put(
+        f"/api/v1/corpora/{corpus.id}/model",
+        json={"model_id": "gemini-1.5-pro", "provider_type": "google_ai_studio"},
+    )
+    resp2 = await async_client.put(
+        f"/api/v1/corpora/{corpus.id}/model",
+        json={"model_id": "gemini-2.0-flash", "provider_type": "google_ai_studio"},
+    )
+    data = resp2.json()
+    assert data["selected_model_id"] == "gemini-2.0-flash"
+
+
+@pytest.mark.asyncio
+async def test_set_model_then_get(async_client, db_session):
+    """Après PUT, GET retourne le même modèle."""
+    corpus = await _make_corpus(db_session)
+    await async_client.put(
+        f"/api/v1/corpora/{corpus.id}/model",
+        json={"model_id": "gemini-2.0-flash", "provider_type": "google_ai_studio"},
+    )
+    get_data = (await async_client.get(f"/api/v1/corpora/{corpus.id}/model")).json()
+    assert get_data["selected_model_id"] == "gemini-2.0-flash"
+
+
+@pytest.mark.asyncio
+async def test_set_model_display_name_fallback(async_client, db_session):
+    """Sans display_name, l'id est utilisé comme display_name."""
+    corpus = await _make_corpus(db_session)
+    data = (await async_client.put(
+        f"/api/v1/corpora/{corpus.id}/model",
+        json={"model_id": "gemini-2.0-flash", "provider_type": "google_ai_studio"},
+    )).json()
+    assert data["selected_model_display_name"] == "gemini-2.0-flash"
+
+
+# ---------------------------------------------------------------------------
+# GET /api/v1/corpora/{id}/model
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_get_model_corpus_not_found(async_client):
+    response = await async_client.get("/api/v1/corpora/nonexistent/model")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_get_model_not_configured(async_client, db_session):
+    """Corpus sans modèle configuré → 404."""
+    corpus = await _make_corpus(db_session)
+    response = await async_client.get(f"/api/v1/corpora/{corpus.id}/model")
+    assert response.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_get_model_ok(async_client, db_session):
+    corpus = await _make_corpus(db_session)
+    await async_client.put(
+        f"/api/v1/corpora/{corpus.id}/model",
+        json={"model_id": "gemini-2.0-flash", "provider_type": "google_ai_studio"},
+    )
+    response = await async_client.get(f"/api/v1/corpora/{corpus.id}/model")
+    assert response.status_code == 200
+
+
+@pytest.mark.asyncio
+async def test_get_model_fields(async_client, db_session):
+    corpus = await _make_corpus(db_session)
+    await async_client.put(
+        f"/api/v1/corpora/{corpus.id}/model",
+        json={"model_id": "gemini-1.5-pro", "provider_type": "google_ai_studio", "display_name": "Gemini 1.5 Pro"},
+    )
+    data = (await async_client.get(f"/api/v1/corpora/{corpus.id}/model")).json()
+    assert data["corpus_id"] == corpus.id
+    assert data["selected_model_id"] == "gemini-1.5-pro"
+    assert data["selected_model_display_name"] == "Gemini 1.5 Pro"
+    assert data["provider_type"] == "google_ai_studio"
+    assert "updated_at" in data