Imago est un hub Backend & Traitement IA multi-tenant open-source dédié à la gestion d'images. Conçu pour propulser des applications frontend riches (comme Shaarli), il offre un stockage média hautement concurrent, des traitements asynchrones planifiés, une observabilité complète du pipeline et des intégrations poussées avec l'Intelligence Artificielle.

✨ Fonctionnalités Principales

📸 API d'Upload & Stockage : Stockage d'images isolé par client (multi-tenant), génération automatique de miniatures, support S3 (MinIO) ou stockage local.
🔍 Extraction de Métadonnées : Découverte en temps réel des données EXIF, géolocalisation GPS, résolution et caractéristiques des fichiers.
📝 Pipelines OCR : Extraction de texte hors-ligne intégrée aux images via le moteur Tesseract.
🤖 Vision IA Intégrée : Résumé automatique de contenu, description de scènes, et classification par tags (Propulsé par les API Gemini & OpenRouter).
⚡ Flux de Données en Temps Réel : Streaming d'événements WebSocket encapsulant les opérations lourdes de la file d'attente (ARQ / Redis).
🔐 Sécurité & Multi-tenancy : Authentification par clé API, gestion de quotas (Rate Limiting) basés sur des plans, isolation totale des données entre les clients.
💻 Portail d'Administration : Interface React complète pour gérer les clients API, surveiller la file d'attente et consulter les métriques.

📚 Documentation Complète

Pour une compréhension approfondie du projet, veuillez consulter les documents suivants dans le répertoire doc/ :

📖 Guide d'Utilisateur (USER_GUIDE.md) : Explications détaillées sur l'utilisation des fonctionnalités, le portail admin et les concepts clés.
🏗️ Architecture (ARCHITECTURE.md) : Plongée technique dans la stack (FastAPI, React, Redis, ARQ, MinIO) et le fonctionnement du pipeline asynchrone.
📡 Guide de l'API (API_GUIDE.md) : Référence complète des endpoints REST, de l'authentification et des exemples de requêtes.
🔌 Guide SDK Python & WebSockets : (Dans le dossier docs/) Pour l'intégration programmatique bas-niveau.

Note: La spécification OpenAPI pour l'écosystème /api/v1/ peut être consultée dynamiquement sur http://localhost:8000/docs (une fois l'application lancée).

🚀 Installation via Docker (Recommandé)

Le projet fournit une configuration docker-compose.yml complète qui orchestre tous les services nécessaires :

admin : Portail d'administration (React + Nginx) sur le port 3000
backend : API Imago (FastAPI) sur le port 8000
db : Base de données PostgreSQL
redis : Serveur Redis (Broker & Cache)
worker : Worker ARQ pour les tâches IA & OCR en arrière-plan
minio : Serveur de stockage objet compatible S3 sur les ports 9000 (API) et 9001 (Console)

Étapes de déploiement

# 1. Cloner le dépôt
git clone <repo_url>
cd imago

# 2. Configuration de l'environnement
cp .env.example .env
# (Éditez le fichier .env si nécessaire, notamment pour ajouter vos clés API IA : GEMINI_API_KEY ou OPENROUTER_API_KEY)

# 3. Lancer toute la stack
docker-compose up -d --build

# 4. Appliquer les migrations de base de données (si non faites automatiquement)
docker-compose exec backend alembic upgrade head

L'API sera disponible sur http://localhost:8000 et le panel admin sur http://localhost:3000.

💻 Installation Locale (Développement)

Si vous souhaitez exécuter le projet sans Docker (nécessite Python 3.10+, PostgreSQL ou SQLite, Redis et Tesseract OCR) :

# 1. Setup Venv
pip install -r requirements.txt

# 2. Base de données & Migrations
cp .env.example .env
alembic upgrade head

# 3. Démarrage
python run.py       # API Endpoint -> http://localhost:8000
python worker.py    # Required ARQ Redis Jobs

🧪 Tests

Nous exécutons une suite de tests automatisée résiliente (80+ tests) simulant nativement des buckets S3 et l'infrastructure ARQ sans dépendance réseau externe :

make test
# Ou directement :
pytest tests/ -v

Veuillez consulter le CHANGELOG.md pour suivre les développements majeurs.