Imago/docs/USER_GUIDE.md

Guide d'Utilisation - Imago Hub

Bienvenue dans le guide d'utilisation d'Imago Hub. Ce document vous accompagnera dans l'utilisation des principales fonctionnalités de la plateforme, que vous interagissiez via l'API, le panel d'administration ou les SDKs.

---

📸 1. Gestion des Images

Upload et Traitement Asynchrone

Imago est conçu pour ingérer rapidement des images et déléguer les traitements lourds (redimensionnement, IA, OCR) en arrière-plan (via les workers ARQ).

Lorsqu'une image est uploadée :

1. Stockage immédiat : L'image originale est sauvegardée localement (ou sur S3/MinIO).
2. Création Miniature : Une version allégée est générée.
3. Mise en file d'attente : L'image passe par un pipeline d'analyse :
   • Extraction EXIF.
   • Passage dans le moteur OCR.
   • Analyse par la Vision IA.

Suivre l'état d'un traitement

Étant donné que les IA (comme Gemini/OpenRouter) et l'OCR prennent du temps, l'upload retourne instantanément un id avec un statut processing ou pending. Vous pouvez surveiller ce statut via :

• Le polling de l'endpoint : GET /api/v1/images/{id}/status
• Le streaming d'événements : Les applications frontend peuvent se connecter aux websockets d'Imago pour être notifiées en temps réel à chaque étape du pipeline. (Voir websocket.md)

---

🤖 2. Intelligence Artificielle et OCR

L'OCR (Reconnaissance Optique de Caractères)

Si activé, le moteur Tesseract parcourt chaque image pour en extraire le texte. Cela est particulièrement utile pour :

• Effectuer des recherches en texte intégral sur des captures d'écran, factures ou mémos photographiés.
• Lier ces données textuelles à l'image sans intervention humaine.

Vision IA (Gemini / OpenRouter)

Imago est "AI-Native". Lorsqu'une image est traitée, elle est envoyée au fournisseur configuré (par exemple : gemini-1.5-pro ou qwen2.5-vl via OpenRouter). L'IA réalise deux opérations clés :

1. Description enrichie : Elle rédige un résumé détaillé de la scène ou du document pour améliorer l'accessibilité et la compréhension.
2. Génération de Tags : Elle attribue entre 5 et 10 mots-clés (tags) pertinents qui seront indexés en base de données, rendant l'image facilement trouvable lors des recherches futures.

---

💻 3. Le Portail d'Administration

Le panel Admin (React) est accessible par défaut sur http://localhost:3000.

Tableau de Bord

Le tableau de bord centralise toutes les images importées. Il permet de :

• Naviguer paginer parmi les milliers d'images gérées.
• Voir en un coup d'œil quelles images sont encore en cours de traitement, ont échoué ou sont validées.
• Filtrer par les Tags générés par l'IA.

Visionneuse Détaillée

En cliquant sur une image, vous avez accès à une vue à 360° :

• L'image originale et sa miniature.
• L'onglet "Sources & EXIF" : Données de géolocalisation pour retracer le parcours de la photo, spécificités techniques (ouverture, ISO, modèle d'appareil).
• L'onglet "Texte & IA" : Le dictionnaire des termes générés par l'OCR et le résumé humain traduit.

Gestion des Clients (Multi-tenancy)

(Si vous possédez la permission admin)

• Vous pouvez gérer les accès API directement depuis l'interface.
• Créer de nouveaux espaces (clients), générer des clés API et imputer des quotas (free, standard, premium) limitant le taux horaire de requêtes par tenant.

---

🔗 4. Interagir avec l'API

Tous les endpoints nécessitent une clé API valide (fournie par l'admin) transmise via le header d'Auth : Authorization: Bearer <votre_cle>

Pour le catalogue exhaustif des endpoints (Upload, Recherche, AI standalone), référez-vous au : 👉 Guide détaillé de l'API (API_GUIDE.md)

Résumé rapide des endpoints utiles :

Action	Endpoint REST	Exemple d'Usage
Envoyer	POST /api/v1/images/upload	Intégrer depuis votre app mobile.
Chercher	GET /api/v1/images?search=voiture	Trouver une image via l'OCR ou les tags IA.
Santé	GET /health/detailed	Surveiller l'état de Redis, DB, et MinIO.