# 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](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)](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. |