Create product and technical specification document

Added a comprehensive product and technical specification document outlining the objectives, features, architecture, and development phases for the IIIF research portal application.

specs.md

@@ -0,0 +1,1160 @@
+# Spécification produit et technique
+
+## Portail universel de recherche IIIF + lecture Mirador + connecteurs MCP
+
+## 1. Résumé exécutif
+
+Objectif : créer une application web déployable sur un Hugging Face Space permettant de rechercher des objets patrimoniaux dans plusieurs bibliothèques et musées numériques du monde, d’afficher une galerie de résultats unifiée, puis d’ouvrir directement les objets sélectionnés dans Mirador pour lecture, comparaison et navigation.
+
+Le produit doit être pensé comme trois couches distinctes :
+
+1. **Couche découverte** : moteur fédéré de recherche multi-sources.
+2. **Couche lecture** : viewer IIIF basé sur Mirador.
+3. **Couche interopérabilité** : API interne normalisée et outils MCP permettant à un agent IA ou à un autre client de lancer une recherche, récupérer un manifest et ouvrir une ressource dans Mirador.
+
+Le projet ne doit pas supposer que Mirador sait faire la recherche. Mirador est uniquement la couche d’affichage.
+
+---
+
+## 2. Vision produit
+
+### 2.1 Problème
+
+Aujourd’hui, les ressources IIIF sont dispersées entre de nombreuses institutions. Même quand les objets sont accessibles, l’utilisateur doit souvent :
+
+* connaître l’institution à l’avance ;
+* chercher sur plusieurs interfaces différentes ;
+* comprendre des modèles de données hétérogènes ;
+* récupérer manuellement les manifests ;
+* changer de viewer selon l’établissement.
+
+### 2.2 Proposition de valeur
+
+Le produit doit offrir une expérience simple :
+
+**Chercher partout, lire tout de suite, comparer dans le même viewer.**
+
+### 2.3 Utilisateurs cibles
+
+* chercheurs en histoire, histoire de l’art, philologie, humanités numériques ;
+* conservateurs, documentalistes, bibliothécaires ;
+* étudiants ;
+* amateurs avancés ;
+* développeurs IA ou agents utilisant MCP.
+
+### 2.4 Promesse utilisateur
+
+Un utilisateur tape une requête unique, obtient une galerie d’objets provenant de plusieurs institutions, filtre les résultats, puis ouvre un ou plusieurs objets dans Mirador sans avoir à manipuler les manifests manuellement.
+
+---
+
+## 3. Périmètre du MVP
+
+Le MVP doit rester réaliste, robuste et simple à déployer.
+
+### 3.1 Ce que le MVP doit faire
+
+* proposer une recherche fédérée sur un petit nombre de sources initiales ;
+* normaliser les résultats dans un format unique ;
+* afficher une galerie de résultats ;
+* ouvrir un résultat dans Mirador via son manifest IIIF ;
+* permettre l’ouverture de plusieurs objets en parallèle dans Mirador ;
+* exposer les fonctions principales via une API interne ;
+* exposer éventuellement ces fonctions via MCP.
+
+### 3.2 Sources initiales recommandées pour le MVP
+
+Commencer avec 3 à 5 connecteurs maximum.
+
+Je recommande :
+
+* Gallica / BnF
+* Bodleian Digital
+* Europeana
+* un connecteur générique IIIF manifest-by-URL
+* éventuellement une source de démonstration simple et stable
+
+### 3.3 Ce que le MVP ne doit pas faire
+
+* pas de moissonnage global du web patrimonial ;
+* pas d’index mondial complet ;
+* pas de promesse de couverture exhaustive ;
+* pas de création de compte utilisateur ;
+* pas d’annotation collaborative persistante dans la première version ;
+* pas de recherche plein texte universelle sur tous les OCR du monde.
+
+---
+
+## 4. Principes de conception
+
+### 4.1 Architecture modulaire
+
+Chaque source doit être branchée via un connecteur indépendant. L’ajout d’une nouvelle institution ne doit pas nécessiter de modifier le cœur applicatif.
+
+### 4.2 Dégradation élégante
+
+Si une source ne fournit pas toutes les métadonnées attendues, le système doit renvoyer un résultat partiel plutôt qu’un échec global.
+
+### 4.3 Transparence
+
+Chaque résultat doit afficher clairement :
+
+* l’institution source ;
+* le type de source ;
+* l’URL de notice ;
+* la disponibilité ou non d’un manifest IIIF ;
+* les droits si connus.
+
+### 4.4 IIIF-first mais pas IIIF-only
+
+Le système privilégie les ressources IIIF, mais il doit accepter que certains catalogues aient une recherche propre et un accès au manifest indirect.
+
+### 4.5 Viewer séparé du moteur
+
+Mirador ne contient aucune logique de recherche métier. Il reçoit des manifests déjà identifiés par la couche découverte.
+
+---
+
+## 5. Cas d’usage
+
+### 5.1 Recherche simple
+
+L’utilisateur tape « book of hours » et voit des résultats venant de plusieurs institutions.
+
+### 5.2 Filtrage
+
+L’utilisateur filtre par institution, type d’objet, langue, période ou disponibilité IIIF.
+
+### 5.3 Lecture
+
+L’utilisateur clique sur un résultat et l’objet s’ouvre dans Mirador.
+
+### 5.4 Comparaison
+
+L’utilisateur sélectionne plusieurs résultats et les ouvre côte à côte dans Mirador.
+
+### 5.5 Import manuel
+
+L’utilisateur colle l’URL d’un manifest IIIF ou d’une notice ; le système tente de détecter le manifest et l’ouvre.
+
+### 5.6 Usage agentique
+
+Un agent appelle le serveur MCP pour rechercher « Dante manuscript », filtre les résultats par institution, récupère les manifests et renvoie au client une URL d’ouverture dans Mirador.
+
+---
+
+## 6. Fonctionnalités détaillées
+
+## 6.1 Onglet Recherche
+
+Doit contenir :
+
+* champ de recherche plein texte ;
+* bouton rechercher ;
+* filtres latéraux ;
+* sélecteur de sources ;
+* mode recherche simple / avancée ;
+* affichage galerie ;
+* pagination ou scroll infini.
+
+### 6.1.1 Recherche simple
+
+Un seul champ libre interroge plusieurs sources.
+
+### 6.1.2 Recherche avancée
+
+Champs optionnels :
+
+* mots-clés ;
+* institution ;
+* type de document ;
+* langue ;
+* date min ;
+* date max ;
+* disponibilité IIIF ;
+* présence d’image ;
+* présence d’OCR.
+
+### 6.1.3 Galerie de résultats
+
+Chaque carte doit afficher :
+
+* miniature ;
+* titre ;
+* institution ;
+* type d’objet ;
+* date ;
+* auteur / créateur si disponible ;
+* indicateur IIIF ;
+* indicateur OCR ;
+* lien notice ;
+* bouton « Ouvrir dans Mirador » ;
+* case à cocher « comparer ».
+
+## 6.2 Onglet Lecture
+
+Cet onglet embarque Mirador.
+
+Fonctions attendues :
+
+* ouverture d’un manifest ;
+* ouverture de plusieurs manifests ;
+* disposition multi-fenêtres ;
+* zoom, rotation, navigation canvas/page ;
+* panneau métadonnées ;
+* bouton partage d’URL ;
+* bouton retour résultats.
+
+## 6.3 Barre d’actions rapides
+
+Visible depuis les cartes de résultats :
+
+* ouvrir ;
+* ajouter à la comparaison ;
+* copier manifest ;
+* copier notice ;
+* ouvrir dans un nouvel onglet.
+
+## 6.4 Import manuel
+
+Une interface doit permettre :
+
+* de coller une URL de manifest ;
+* de coller une URL de notice ;
+* de saisir un identifiant connu selon certaines sources.
+
+Le backend tente alors :
+
+1. de reconnaître la source ;
+2. de récupérer le manifest ;
+3. de charger Mirador.
+
+## 6.5 Journal de transparence
+
+Pour chaque résultat, un panneau optionnel « Voir la provenance » doit pouvoir afficher :
+
+* connecteur utilisé ;
+* requête envoyée ;
+* temps de réponse ;
+* niveau de confiance de normalisation ;
+* champs absents.
+
+---
+
+## 7. Architecture globale
+
+## 7.1 Vue d’ensemble
+
+Le système comporte :
+
+### Frontend
+
+* application React ou Next.js ;
+* interface utilisateur ;
+* intégration Mirador ;
+* gestion de l’état ;
+* appel à l’API backend.
+
+### Backend
+
+* FastAPI ;
+* orchestrateur de recherche ;
+* normalisation des métadonnées ;
+* cache ;
+* résolution de manifests ;
+* endpoints REST ;
+* couche MCP optionnelle.
+
+### Déploiement
+
+* Hugging Face Space Docker ;
+* variables d’environnement ;
+* stockage léger pour cache local ;
+* logs standardisés.
+
+---
+
+## 8. Choix techniques recommandés
+
+## 8.1 Frontend
+
+* React + TypeScript
+* Vite ou Next.js
+* TanStack Query pour les appels réseau
+* Zustand ou Redux Toolkit pour l’état global
+* composant Mirador intégré dans une vue dédiée
+* Tailwind CSS pour l’UI
+
+## 8.2 Backend
+
+* Python 3.11+
+* FastAPI
+* httpx pour appels asynchrones
+* pydantic pour modèles
+* cachetools ou redis optionnel si disponible
+* structlog ou logging JSON
+
+## 8.3 MCP
+
+* couche séparée, facultative au démarrage
+* outils exposés par-dessus les mêmes services métiers que le REST
+* surtout aucune logique dupliquée entre REST et MCP
+
+## 8.4 Déploiement
+
+* conteneur unique au MVP
+* frontend servi soit statiquement, soit via le backend
+* config simple via variables d’environnement
+
+---
+
+## 9. Architecture logique détaillée
+
+## 9.1 Modules backend
+
+### a. Search Orchestrator
+
+Responsabilités :
+
+* recevoir une requête utilisateur ;
+* sélectionner les connecteurs à appeler ;
+* lancer les appels en parallèle ;
+* agréger les réponses ;
+* normaliser les résultats ;
+* classer ;
+* renvoyer la réponse unifiée.
+
+### b. Connector Registry
+
+Registre de tous les connecteurs disponibles.
+
+Fonctions :
+
+* lister les connecteurs ;
+* indiquer leurs capacités ;
+* savoir lesquels sont activés ;
+* fournir l’instance du connecteur demandé.
+
+### c. Source Connectors
+
+Un connecteur par source.
+
+Interface commune obligatoire :
+
+* `search(query, filters, page, page_size)`
+* `get_item(source_id)`
+* `resolve_manifest(item_or_url)`
+* `healthcheck()`
+* `capabilities()`
+
+### d. Normalization Layer
+
+Transforme des réponses hétérogènes en schéma commun.
+
+### e. Manifest Resolver
+
+Essaye de trouver un manifest à partir de :
+
+* métadonnées de résultat ;
+* URL de notice ;
+* endpoint spécifique de la source ;
+* heuristiques configurées.
+
+### f. Cache Layer
+
+Cache des requêtes de recherche et des résolutions de manifest.
+
+### g. MCP Adapter
+
+Expose certains services backend sous forme d’outils MCP.
+
+---
+
+## 10. Contrat des connecteurs
+
+Chaque connecteur doit implémenter une classe abstraite commune.
+
+### 10.1 Interface conceptuelle
+
+```python
+class BaseConnector(ABC):
+    name: str
+    source_type: str
+
+    @abstractmethod
+    async def search(self, query: str, filters: dict, page: int, page_size: int) -> SearchResultPage:
+        ...
+
+    @abstractmethod
+    async def get_item(self, source_id: str) -> NormalizedItem | None:
+        ...
+
+    @abstractmethod
+    async def resolve_manifest(self, item: NormalizedItem | None = None, url: str | None = None) -> str | None:
+        ...
+
+    @abstractmethod
+    async def capabilities(self) -> dict:
+        ...
+
+    @abstractmethod
+    async def healthcheck(self) -> dict:
+        ...
+```
+
+### 10.2 Capacités déclaratives
+
+Un connecteur doit déclarer explicitement :
+
+* recherche libre oui/non ;
+* recherche structurée oui/non ;
+* pagination oui/non ;
+* facettes oui/non ;
+* résolution manifest directe oui/non ;
+* OCR signalé oui/non ;
+* miniature disponible oui/non.
+
+---
+
+## 11. Schéma de données normalisé
+
+## 11.1 Objet principal : NormalizedItem
+
+```json
+{
+  "id": "global-unique-id",
+  "source": "gallica",
+  "source_label": "Gallica / BnF",
+  "source_item_id": "ark-or-internal-id",
+  "title": "string",
+  "subtitle": "string|null",
+  "creators": ["string"],
+  "date_display": "string|null",
+  "date_sort": "string|null",
+  "languages": ["string"],
+  "object_type": "manuscript|book|image|map|newspaper|other",
+  "description": "string|null",
+  "thumbnail_url": "string|null",
+  "preview_image_url": "string|null",
+  "institution": "string|null",
+  "collection": "string|null",
+  "rights": "string|null",
+  "license": "string|null",
+  "record_url": "string|null",
+  "manifest_url": "string|null",
+  "iiif_image_service_url": "string|null",
+  "has_iiif_manifest": true,
+  "has_images": true,
+  "has_ocr": false,
+  "availability": "public|restricted|unknown",
+  "relevance_score": 0.0,
+  "raw_source_payload": {},
+  "normalization_warnings": ["string"]
+}
+```
+
+## 11.2 Réponse de recherche
+
+```json
+{
+  "query": "book of hours",
+  "page": 1,
+  "page_size": 24,
+  "total_estimated": 214,
+  "results": [],
+  "sources_used": ["gallica", "bodleian", "europeana"],
+  "partial_failures": [
+    {
+      "source": "bodleian",
+      "error": null,
+      "status": "ok"
+    }
+  ],
+  "duration_ms": 942,
+  "facets": {
+    "source": [],
+    "object_type": [],
+    "language": []
+  }
+}
+```
+
+---
+
+## 12. API REST interne
+
+## 12.1 Endpoints principaux
+
+### `GET /api/health`
+
+Retourne l’état global de l’application.
+
+### `GET /api/sources`
+
+Retourne la liste des connecteurs actifs et leurs capacités.
+
+### `POST /api/search`
+
+Entrée :
+
+```json
+{
+  "query": "book of hours",
+  "sources": ["gallica", "bodleian"],
+  "filters": {
+    "object_type": ["manuscript"],
+    "language": ["lat"],
+    "has_iiif_manifest": true
+  },
+  "page": 1,
+  "page_size": 24,
+  "sort": "relevance"
+}
+```
+
+Sortie : SearchResponse normalisée.
+
+### `GET /api/item/{global_id}`
+
+Retourne le détail d’un item normalisé.
+
+### `POST /api/resolve-manifest`
+
+Entrée :
+
+```json
+{
+  "source": "gallica",
+  "source_item_id": "identifier",
+  "record_url": "optional"
+}
+```
+
+Sortie :
+
+```json
+{
+  "manifest_url": "https://.../manifest",
+  "status": "resolved",
+  "method": "metadata|heuristic|source-api"
+}
+```
+
+### `POST /api/open`
+
+Entrée :
+
+```json
+{
+  "manifest_urls": ["https://example.org/manifest/1"],
+  "workspace": "default"
+}
+```
+
+Sortie :
+
+```json
+{
+  "mirador_state": {}
+}
+```
+
+### `POST /api/import`
+
+Permet d’importer une URL libre.
+
+Entrée :
+
+```json
+{
+  "url": "https://example.org/item/or/manifest"
+}
+```
+
+Sortie :
+
+```json
+{
+  "detected_source": "bodleian",
+  "record_url": "...",
+  "manifest_url": "...",
+  "item": {}
+}
+```
+
+---
+
+## 13. Outils MCP à exposer
+
+Le serveur MCP doit réutiliser les mêmes services métiers que l’API REST.
+
+### Outils minimum
+
+#### `search_items`
+
+Paramètres :
+
+* query
+* sources
+* filters
+* page
+* page_size
+
+Retour : liste normalisée de résultats.
+
+#### `get_item`
+
+Paramètres :
+
+* global_id
+
+Retour : détail d’un item.
+
+#### `resolve_manifest`
+
+Paramètres :
+
+* global_id ou URL
+
+Retour : manifest URL.
+
+#### `open_in_mirador`
+
+Paramètres :
+
+* une ou plusieurs manifest URLs
+
+Retour : URL d’ouverture ou état Mirador sérialisé.
+
+#### `list_sources`
+
+Retour : sources actives et capacités.
+
+### Ressources MCP éventuelles
+
+* catalogue des sources
+* documentation des schémas
+* exemples de requêtes
+
+---
+
+## 14. Intégration Mirador
+
+## 14.1 Attentes fonctionnelles
+
+Mirador doit être embarqué comme composant de lecture.
+
+L’application doit pouvoir :
+
+* initialiser Mirador avec zéro, une ou plusieurs fenêtres ;
+* injecter dynamiquement les manifests sélectionnés ;
+* mémoriser l’état courant de la session ;
+* permettre un partage d’URL si possible.
+
+## 14.2 Mode d’intégration
+
+Créer un composant `MiradorWorkspace` qui reçoit une liste de manifests et une configuration.
+
+Exemple de props :
+
+```ts
+interface MiradorWorkspaceProps {
+  manifestUrls: string[]
+  initialView?: "single" | "compare"
+  showMetadata?: boolean
+  onStateChange?: (state: unknown) => void
+}
+```
+
+## 14.3 État applicatif
+
+Le frontend doit stocker séparément :
+
+* résultats de recherche ;
+* sélection pour comparaison ;
+* manifests ouverts ;
+* configuration du workspace.
+
+---
+
+## 15. UI et UX détaillées
+
+## 15.1 Navigation principale
+
+* onglet Recherche
+* onglet Lecture
+* onglet Import
+* onglet Sources
+* onglet À propos
+
+## 15.2 Page Recherche
+
+### Colonne gauche
+
+* sources
+* type d’objet
+* période
+* langue
+* disponibilité IIIF
+* présence OCR
+
+### Zone centrale
+
+* barre de recherche
+* tri
+* nombre de résultats
+* cartes résultats
+
+### Colonne droite optionnelle
+
+* panier de comparaison
+* aperçu rapide du résultat sélectionné
+
+## 15.3 Cartes résultats
+
+Doivent être lisibles, homogènes et sobres.
+
+Actions visibles :
+
+* ouvrir
+* comparer
+* détails
+
+## 15.4 Page Lecture
+
+* bandeau avec titres des objets ouverts
+* zone Mirador principale
+* panneau latéral avec métadonnées et provenance
+
+## 15.5 Page Sources
+
+Affiche pour chaque source :
+
+* nom
+* description
+* statut
+* capacités
+* notes spécifiques
+* exemple de requête test
+
+---
+
+## 16. Classement et fusion des résultats
+
+Le système doit agréger des résultats hétérogènes. Il faut donc définir une stratégie de ranking simple au MVP.
+
+### 16.1 Score de base
+
+Combiner :
+
+* score natif de la source si disponible ;
+* qualité de correspondance textuelle locale ;
+* disponibilité d’un manifest ;
+* présence d’une miniature ;
+* complétude des métadonnées.
+
+### 16.2 Déduplication légère
+
+Tenter de détecter des doublons faibles via :
+
+* titre normalisé ;
+* identifiants communs ;
+* URLs canoniques ;
+* manifest identique.
+
+En cas de doute, ne pas fusionner automatiquement au MVP.
+
+---
+
+## 17. Performance et robustesse
+
+## 17.1 Appels concurrents
+
+Le backend doit appeler les connecteurs en parallèle avec timeout par source.
+
+## 17.2 Timeouts
+
+Chaque source doit avoir :
+
+* timeout connexion ;
+* timeout lecture ;
+* timeout global par requête.
+
+## 17.3 Partial success
+
+Si une source échoue, les autres résultats doivent quand même apparaître.
+
+## 17.4 Cache
+
+Mettre en cache :
+
+* résultats de recherche récents ;
+* résolutions de manifest ;
+* capacités des sources.
+
+## 17.5 Limitation
+
+Ajouter un plafond raisonnable de sources interrogées simultanément au MVP.
+
+---
+
+## 18. Sécurité et conformité
+
+## 18.1 Sécurité minimale
+
+* validation stricte des URLs importées ;
+* blocage des schémas non autorisés ;
+* prévention SSRF basique ;
+* limitation des domaines si nécessaire ;
+* logs sans données sensibles.
+
+## 18.2 Respect des sources
+
+* afficher la source d’origine ;
+* ne pas masquer les droits ;
+* ne pas revendiquer la propriété des données ;
+* lien systématique vers la notice d’origine.
+
+## 18.3 CORS et proxy
+
+Prévoir un backend pouvant agir comme intermédiaire pour certains appels si le frontend rencontre des restrictions cross-origin.
+
+---
+
+## 19. Observabilité
+
+Prévoir :
+
+* logs structurés ;
+* mesure des temps par source ;
+* taux de résolution des manifests ;
+* taux d’échec par connecteur ;
+* nombre moyen de résultats par source.
+
+---
+
+## 20. Arborescence de projet recommandée
+
+```text
+app/
+  frontend/
+    src/
+      components/
+      pages/
+      hooks/
+      store/
+      lib/
+      types/
+  backend/
+    app/
+      api/
+      services/
+      connectors/
+      models/
+      mcp/
+      utils/
+      config/
+  tests/
+    unit/
+    integration/
+  docs/
+  Dockerfile
+  docker-compose.yml
+  README.md
+```
+
+---
+
+## 21. Plan de développement par étapes
+
+## Phase 1 — socle
+
+* boot frontend ;
+* boot backend ;
+* endpoint health ;
+* intégration Mirador minimale ;
+* schéma `NormalizedItem`.
+
+## Phase 2 — connecteurs MVP
+
+* connecteur Gallica ;
+* connecteur Bodleian ;
+* connecteur Europeana ;
+* registre de connecteurs ;
+* orchestration de recherche.
+
+## Phase 3 — UX recherche
+
+* galerie ;
+* filtres ;
+* pagination ;
+* détail item ;
+* ouverture Mirador.
+
+## Phase 4 — import et résolution
+
+* import URL ;
+* résolution manifest ;
+* comparaison multi-fenêtres.
+
+## Phase 5 — MCP
+
+* outils minimum ;
+* documentation ;
+* exemples clients.
+
+## Phase 6 — polissage
+
+* cache ;
+* logs ;
+* robustesse ;
+* amélioration ranking.
+
+---
+
+## 22. Critères d’acceptation du MVP
+
+Le MVP est considéré comme acceptable si :
+
+1. une requête simple renvoie des résultats depuis au moins trois sources ;
+2. les résultats sont affichés dans une galerie homogène ;
+3. au moins 80 % des résultats disposant réellement d’un manifest peuvent être ouverts dans Mirador ;
+4. l’ouverture de plusieurs objets dans Mirador fonctionne ;
+5. l’échec d’une source n’empêche pas la réponse globale ;
+6. l’API `/api/sources` décrit clairement les capacités ;
+7. l’import d’une URL de manifest fonctionne ;
+8. les fonctions principales sont exposées aussi via MCP si la couche MCP est activée.
+
+---
+
+## 23. Non-objectifs explicites
+
+Le document doit clairement indiquer ce que le produit n’est pas :
+
+* ce n’est pas un moteur de recherche web généraliste ;
+* ce n’est pas un catalogue mondial exhaustif ;
+* ce n’est pas une base propriétaire remplaçant les institutions ;
+* ce n’est pas un viewer maison destiné à remplacer Mirador ;
+* ce n’est pas une solution d’annotation scientifique complète au MVP.
+
+---
+
+## 24. Spécification pour génération de code par LLM
+
+Le LLM chargé de coder le projet doit respecter les consignes suivantes.
+
+### 24.1 Contraintes générales
+
+* tout le code doit être typé ;
+* tout le code doit être modulaire ;
+* aucune logique métier dupliquée entre REST et MCP ;
+* chaque connecteur doit être isolé ;
+* chaque fonction publique doit avoir docstring ou commentaire clair ;
+* les erreurs doivent être gérées proprement ;
+* les appels réseau doivent être asynchrones côté backend.
+
+### 24.2 Contraintes frontend
+
+* TypeScript strict ;
+* composants réutilisables ;
+* éviter les dépendances inutiles ;
+* UI simple et claire ;
+* aucun style inline massif ;
+* préférer Tailwind.
+
+### 24.3 Contraintes backend
+
+* FastAPI ;
+* modèles Pydantic ;
+* services séparés des routes ;
+* tests unitaires des connecteurs ;
+* tests d’intégration des endpoints.
+
+### 24.4 Livrables attendus du LLM
+
+* code complet frontend ;
+* code complet backend ;
+* Dockerfile ;
+* README d’installation ;
+* exemples `.env.example` ;
+* tests minimum ;
+* documentation d’API.
+
+---
+
+## 25. Prompt maître pour un LLM codeur
+
+```text
+Tu dois générer un projet complet déployable sur Hugging Face Spaces sous forme d’application web Docker.
+
+Objectif du produit : une interface de recherche fédérée sur plusieurs sources patrimoniales, avec affichage d’une galerie de résultats normalisés, puis ouverture directe des objets dans Mirador à partir de leurs manifests IIIF.
+
+Contraintes :
+- frontend React + TypeScript ;
+- backend FastAPI Python ;
+- architecture modulaire ;
+- connecteurs par source ;
+- schéma de données normalisé ;
+- Mirador intégré comme couche de lecture ;
+- API REST interne ;
+- couche MCP optionnelle mais prévue ;
+- code propre, typé, documenté, testable.
+
+Fonctionnalités MVP :
+- champ de recherche ;
+- sélection de sources ;
+- filtres simples ;
+- galerie de résultats ;
+- bouton ouvrir dans Mirador ;
+- comparaison multi-objets ;
+- import manuel d’URL de manifest ;
+- endpoint listant les sources et capacités.
+
+Architecture attendue :
+- dossier frontend ;
+- dossier backend ;
+- dossier tests ;
+- Dockerfile ;
+- README.
+
+Backend :
+- créer une interface abstraite BaseConnector ;
+- implémenter un registry de connecteurs ;
+- implémenter un orchestrateur de recherche ;
+- définir les modèles Pydantic NormalizedItem, SearchResponse, SourceCapability ;
+- créer les endpoints /api/health, /api/sources, /api/search, /api/item/{id}, /api/resolve-manifest, /api/import.
+
+Frontend :
+- créer une page Recherche ;
+- créer une page Lecture avec Mirador ;
+- créer un store pour la sélection des résultats ;
+- créer des cartes de résultats ;
+- permettre d’ouvrir un ou plusieurs manifests dans Mirador.
+
+Important :
+- ne pas coder de logique de recherche dans Mirador ;
+- séparer nettement découverte et lecture ;
+- gérer les erreurs partielles des sources ;
+- prévoir des mocks si certaines API réelles sont instables.
+
+Commence par générer l’arborescence complète du projet, puis le backend, puis le frontend, puis les tests, puis le Dockerfile et le README.
+```
+
+---
+
+## 26. Prompts spécialisés par lot
+
+## Prompt lot 1 — backend socle
+
+```text
+Génère uniquement le backend FastAPI du projet.
+
+Exigences :
+- Python 3.11+
+- FastAPI
+- Pydantic
+- httpx async
+- architecture modulaire
+- BaseConnector abstraite
+- ConnectorRegistry
+- SearchOrchestrator
+- modèles NormalizedItem, SearchResponse, SourceInfo
+- endpoints : /api/health, /api/sources, /api/search, /api/item/{id}, /api/resolve-manifest, /api/import
+- gestion d’erreurs propre
+- docstrings
+- tests unitaires de base
+
+Ne génère pas encore le frontend.
+```
+
+## Prompt lot 2 — frontend socle
+
+```text
+Génère uniquement le frontend React + TypeScript du projet.
+
+Exigences :
+- page Recherche
+- filtres latéraux
+- galerie de résultats
+- composant ResultCard
+- store global pour manifests sélectionnés
+- page Lecture intégrant Mirador
+- navigation simple entre Recherche et Lecture
+- Tailwind CSS
+- code propre et typé
+
+Le frontend doit appeler les endpoints du backend déjà définis.
+```
+
+## Prompt lot 3 — connecteurs
+
+```text
+Ajoute au backend un système de connecteurs source.
+
+Exigences :
+- implémenter BaseConnector
+- créer au moins 3 connecteurs d’exemple
+- chaque connecteur doit renvoyer des résultats normalisés
+- prévoir un mode mock si la source distante n’est pas disponible
+- ne pas dupliquer la logique de normalisation
+```
+
+## Prompt lot 4 — MCP
+
+```text
+Ajoute une couche MCP au backend existant.
+
+Exigences :
+- exposer les outils search_items, get_item, resolve_manifest, open_in_mirador, list_sources
+- réutiliser les mêmes services métiers que les routes REST
+- ne créer aucune duplication de logique
+- fournir un exemple minimal d’utilisation par un client MCP
+```
+
+---
+
+## 27. Backlog post-MVP
+
+Après le MVP, prévoir :
+
+* sauvegarde de sessions ;
+* favoris ;
+* export CSV / JSON des résultats ;
+* partage de workspace Mirador ;
+* annotation persistante ;
+* index local optionnel ;
+* détection de doublons plus avancée ;
+* recherche intra-document via Content Search IIIF quand disponible ;
+* enrichissement sémantique ;
+* facettes avancées ;
+* recommandation d’objets similaires.
+
+---
+
+## 28. Décisions produit à ne pas perdre
+
+1. Mirador est la couche de lecture, jamais la couche de recherche.
+2. Les connecteurs sont les unités fondamentales d’extension.
+3. Le schéma normalisé est le cœur du projet.
+4. Le MVP privilégie la simplicité et la robustesse sur l’exhaustivité.
+5. Le MCP est utile comme surcouche d’interopérabilité, pas comme justification unique du produit.
+
+---
+
+## 29. Version courte à remettre à un développeur ou à un LLM
+
+Créer une application web déployable sur Hugging Face Spaces qui permet de rechercher des objets patrimoniaux dans plusieurs institutions, d’afficher les résultats sous forme de galerie homogène, puis d’ouvrir directement les objets dans Mirador à partir de leurs manifests IIIF.
+
+Le produit comprend :
+
+* un frontend React/TypeScript ;
+* un backend FastAPI ;
+* des connecteurs source modulaires ;
+* un schéma de données normalisé ;
+* Mirador intégré ;
+* une API REST ;
+* une couche MCP optionnelle.
+
+Le MVP doit inclure recherche fédérée, filtres simples, galerie, ouverture Mirador, comparaison multi-objets et import manuel d’URL de manifest.
+
+Le système doit être robuste aux échecs partiels, simple à étendre et proprement documenté.