feat(sprint5-session-a): Dockerisation + configuration HuggingFace Spaces

- infra/Dockerfile : image python:3.11-slim, WORKDIR /app, PYTHONPATH=/app/backend,
port 7860, workers=1, data/ en volume, secrets en variables d'env (R06)
- Dockerfile (racine) : copie identique requise par HF Spaces SDK docker
- infra/docker-compose.yml : dev local, build context=repo root, volume ../data
- README.md : YAML front matter HF + docs développeur (lancer, tester, profils, providers)
- .huggingface/README.md : config Space HF (secrets, stockage Datasets, endpoints)

Convention HF Spaces : Dockerfile obligatoire à la racine → double fichier.
Structure image : /app/backend/app/ + /app/profiles/ + /app/prompts/ + /app/data/ (volume).

https://claude.ai/code/session_018woyEHc8HG2th7V4ewJ4Kg

.huggingface/README.md

@@ -0,0 +1,40 @@
+---
+title: Scriptorium AI
+emoji: 📜
+colorFrom: blue
+colorTo: gold
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+## Configuration HuggingFace Spaces
+
+Ce Space utilise le SDK Docker. L'image est construite depuis le `Dockerfile`
+à la racine du dépôt au moment du push.
+
+### Secrets à configurer
+
+Dans **Settings → Repository secrets**, renseigner selon le provider choisi :
+
+| Secret | Description |
+|--------|-------------|
+| `AI_PROVIDER` | `google_ai_studio` \| `google_ai_api` \| `google_vertex` |
+| `GOOGLE_AI_STUDIO_API_KEY` | Clé API Google AI Studio (si `AI_PROVIDER=google_ai_studio`) |
+| `GOOGLE_AI_API_KEY` | Clé API Google AI (si `AI_PROVIDER=google_ai_api`) |
+| `GOOGLE_VERTEX_PROJECT` | ID du projet GCP (si `AI_PROVIDER=google_vertex`) |
+| `GOOGLE_VERTEX_LOCATION` | Région Vertex (défaut : `us-central1`) |
+
+### Stockage des artefacts
+
+Les images, JSON maîtres et exports XML sont stockés sur un **HuggingFace Dataset**
+associé (pas dans l'image Docker). Le volume `/app/data` doit être monté via
+le Dataset persistant du Space ou un Dataset dédié.
+
+### Endpoints de vérification
+
+```
+GET /api/v1/profiles      → liste les 4 profils de corpus disponibles
+GET /docs                 → documentation Swagger interactive
+GET /api/v1/corpora       → liste des corpus ingérés
+```

Dockerfile

@@ -0,0 +1,47 @@
+# Scriptorium AI — image de production
+# Ce fichier est la copie exacte de infra/Dockerfile.
+# Il est requis à la racine du dépôt pour HuggingFace Spaces (SDK docker).
+#
+# Build depuis la racine du dépôt :
+#   docker build -t scriptorium-ai .
+#
+# Structure attendue dans l'image :
+#   /app/backend/app/   ← source Python (importable via PYTHONPATH)
+#   /app/profiles/      ← profils JSON
+#   /app/prompts/       ← templates de prompts
+#   /app/data/          ← créé vide ; à monter en volume pour les artefacts
+
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# ── Dépendances Python ─────────────────────────────────────────────────────
+# On copie uniquement pyproject.toml pour exploiter le cache de layers Docker.
+# Un stub app/__init__.py satisfait setuptools (discover packages) sans avoir
+# besoin de copier tout le code source à ce stade.
+COPY backend/pyproject.toml /tmp/build/
+RUN mkdir -p /tmp/build/app \
+    && touch /tmp/build/app/__init__.py \
+    && pip install --no-cache-dir /tmp/build/ \
+    && rm -rf /tmp/build
+
+# ── Code source ────────────────────────────────────────────────────────────
+COPY backend/app ./backend/app
+COPY profiles/ ./profiles/
+COPY prompts/ ./prompts/
+
+# ── Répertoire des artefacts (vide dans l'image ; monté en volume) ─────────
+RUN mkdir -p /app/data
+
+# ── Secrets Google AI : JAMAIS dans l'image (R06) ─────────────────────────
+# Passer au runtime via -e ou les Secrets HuggingFace Spaces :
+#   AI_PROVIDER, GOOGLE_AI_STUDIO_API_KEY, GOOGLE_AI_API_KEY,
+#   GOOGLE_VERTEX_PROJECT, GOOGLE_VERTEX_LOCATION
+
+# PYTHONPATH permet l'import `app.main:app` depuis /app/backend/app/
+ENV PYTHONPATH=/app/backend
+
+EXPOSE 7860
+
+# 1 worker au MVP — pas de Gunicorn, pas de multiprocessing
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]

README.md

@@ -1,2 +1,110 @@
-# Scriptorium-AI
-AI-Enhanced Scholarly Edition Generation Platform
+---
+title: Scriptorium AI
+emoji: 📜
+colorFrom: blue
+colorTo: gold
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# Scriptorium AI
+
+Plateforme générique de génération d'éditions savantes augmentées pour documents
+patrimoniaux numérisés : manuscrits médiévaux, incunables, cartulaires, archives,
+chartes, papyri — tout type de document, toute époque, toute langue.
+
+---
+
+## Structure du dépôt
+
+```
+scriptorium-ai/
+├── backend/            # API FastAPI + pipeline Python
+│   ├── app/
+│   │   ├── api/v1/     # endpoints REST (/api/v1/...)
+│   │   ├── models/     # tables SQLAlchemy (SQLite async)
+│   │   ├── schemas/    # modèles Pydantic v2
+│   │   └── services/   # ingest / image / ai / export / search
+│   ├── tests/          # suite pytest (477 tests)
+│   └── pyproject.toml
+├── profiles/           # 4 profils de corpus JSON
+├── prompts/            # templates de prompts par profil
+├── infra/              # Dockerfile + docker-compose (dev local)
+├── Dockerfile          # copie du Dockerfile pour HuggingFace Spaces
+└── data/               # artefacts runtime — NON versionné
+```
+
+---
+
+## Lancer en local (Docker)
+
+```bash
+# 1. Cloner le dépôt
+git clone https://github.com/<org>/scriptorium-ai && cd scriptorium-ai
+
+# 2. Définir les variables d'environnement
+cp .env.example .env          # puis renseigner les clés dans .env
+
+# 3. Démarrer le service
+docker compose -f infra/docker-compose.yml up --build
+
+# 4. Vérifier
+curl http://localhost:7860/api/v1/profiles
+```
+
+L'API est accessible sur `http://localhost:7860`. La documentation interactive
+Swagger est disponible sur `http://localhost:7860/docs`.
+
+---
+
+## Lancer les tests
+
+```bash
+cd backend
+pip install -e ".[dev]"
+pytest tests/ -v --cov=app
+```
+
+Résultat attendu : **477 passed, 3 skipped**.
+
+---
+
+## Profils disponibles
+
+| Profil | Description |
+|--------|-------------|
+| `medieval-illuminated` | Manuscrits médiévaux enluminés (OCR diplomatique, iconographie, commentaire) |
+| `medieval-textual`     | Manuscrits médiévaux textuels (OCR, traduction, commentaire savant) |
+| `early-modern-print`   | Imprimés anciens (incunables, livres des XVIe–XVIIIe siècles) |
+| `modern-handwritten`   | Documents manuscrits modernes (cursive, archives, chartes) |
+
+```bash
+# Lister les profils via l'API
+curl http://localhost:7860/api/v1/profiles
+```
+
+---
+
+## Providers Google AI
+
+Trois modes d'authentification sont supportés. Sélectionner via `AI_PROVIDER`.
+
+| Provider | Variable `AI_PROVIDER` | Variables d'environnement requises |
+|----------|------------------------|-------------------------------------|
+| Google AI Studio (clé API) | `google_ai_studio` | `GOOGLE_AI_STUDIO_API_KEY` |
+| Google AI API (legacy) | `google_ai_api` | `GOOGLE_AI_API_KEY` |
+| Google Vertex AI | `google_vertex` | `GOOGLE_VERTEX_PROJECT`, `GOOGLE_VERTEX_LOCATION` |
+
+Les clés ne doivent **jamais** figurer dans le code, les commits ou l'image Docker.
+Sur HuggingFace Spaces, les renseigner dans **Settings → Repository secrets**.
+
+---
+
+## Déploiement HuggingFace Spaces
+
+Ce dépôt est configuré pour HuggingFace Spaces (SDK Docker, port 7860).
+Les artefacts de traitement (images, JSON maîtres, exports XML) sont stockés
+sur HuggingFace Datasets — pas dans l'image Docker.
+
+Voir `.huggingface/README.md` pour la configuration spécifique du Space.

infra/Dockerfile

@@ -0,0 +1,49 @@
+# Scriptorium AI — image de production
+# Build depuis la racine du dépôt :
+#   docker build -f infra/Dockerfile -t scriptorium-ai .
+#
+# Structure attendue dans l'image :
+#   /app/backend/app/   ← source Python (importable via PYTHONPATH)
+#   /app/profiles/      ← profils JSON
+#   /app/prompts/       ← templates de prompts
+#   /app/data/          ← créé vide ; à monter en volume pour les artefacts
+
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# ── Dépendances système (lxml utilise des wheels binaires pré-compilés ;
+#    aucun outil de build requis sur cette image) ─────────────────────────────
+# Aucun paquet système supplémentaire nécessaire.
+
+# ── Dépendances Python ─────────────────────────────────────────────────────
+# On copie uniquement pyproject.toml pour exploiter le cache de layers Docker.
+# Un stub app/__init__.py satisfait setuptools (discover packages) sans avoir
+# besoin de copier tout le code source à ce stade.
+COPY backend/pyproject.toml /tmp/build/
+RUN mkdir -p /tmp/build/app \
+    && touch /tmp/build/app/__init__.py \
+    && pip install --no-cache-dir /tmp/build/ \
+    && rm -rf /tmp/build
+
+# ── Code source ────────────────────────────────────────────────────────────
+# Copié APRÈS l'installation des dépendances pour conserver le cache.
+COPY backend/app ./backend/app
+COPY profiles/ ./profiles/
+COPY prompts/ ./prompts/
+
+# ── Répertoire des artefacts (vide dans l'image ; monté en volume) ─────────
+RUN mkdir -p /app/data
+
+# ── Secrets Google AI : JAMAIS dans l'image (R06) ─────────────────────────
+# Passer au runtime via -e ou docker-compose environment :
+#   AI_PROVIDER, GOOGLE_AI_STUDIO_API_KEY, GOOGLE_AI_API_KEY,
+#   GOOGLE_VERTEX_PROJECT, GOOGLE_VERTEX_LOCATION
+
+# PYTHONPATH permet l'import `app.main:app` depuis /app/backend/app/
+ENV PYTHONPATH=/app/backend
+
+EXPOSE 7860
+
+# 1 worker au MVP — pas de Gunicorn, pas de multiprocessing
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860", "--workers", "1"]

infra/docker-compose.yml

@@ -0,0 +1,25 @@
+# docker-compose pour développement local UNIQUEMENT.
+# Lancer depuis la racine du dépôt :
+#   docker compose -f infra/docker-compose.yml up --build
+#
+# Les secrets ne doivent jamais figurer dans ce fichier (R06).
+# Copier .env.example → .env et y renseigner les clés.
+
+services:
+  api:
+    build:
+      context: ..            # racine du dépôt = contexte de build
+      dockerfile: infra/Dockerfile
+    ports:
+      - "7860:7860"
+    volumes:
+      - ../data:/app/data    # artefacts montés en volume, hors image
+    environment:
+      # Provider IA : google_ai_studio | google_vertex | google_ai_api
+      - AI_PROVIDER=${AI_PROVIDER:-google_ai_studio}
+      # Clés selon le provider choisi — à définir dans .env
+      - GOOGLE_AI_STUDIO_API_KEY=${GOOGLE_AI_STUDIO_API_KEY:-}
+      - GOOGLE_AI_API_KEY=${GOOGLE_AI_API_KEY:-}
+      - GOOGLE_VERTEX_PROJECT=${GOOGLE_VERTEX_PROJECT:-}
+      - GOOGLE_VERTEX_LOCATION=${GOOGLE_VERTEX_LOCATION:-us-central1}
+    restart: unless-stopped