# 🏗️ Architecture & Fonctionnalités : Animetix

Ce document détaille les choix de conception et l'implémentation technique du projet **Animetix**.

## 1. Architecture du Système IA

Animetix repose sur une architecture **RAG 2.0 (Retrieval-Augmented Generation)** avancée, divisée en trois couches :

### A. Couche de Représentation (Embeddings)
*   **Modèle** : `paraphrase-multilingual-mpnet-base-v2` quantifié en **INT8**.
*   **Espace Latent** : Les œuvres sont projetées dans un espace à 768 dimensions. La quantification dynamique réduit l'empreinte RAM de 450 Mo à ~120 Mo sans perte de précision.
*   **Vector Database** : **ChromaDB** avec indexation HNSW pour des recherches de similarité en millisecondes.

### B. Couche de Raisonnement (Agentic AI)
*   **Pattern ReAct** : L'IA ne génère pas simplement du texte, elle utilise une boucle *Thought -> Action -> Observation*.
*   **Tooling** : L'agent a accès à ChromaDB (mémoire sémantique), Neo4j (mémoire logique) et à la base JSON (faits bruts).
*   **Reranking** : Utilisation de `BGE-Reranker-Base` pour affiner le top 10 des résultats de recherche et garantir un score de 100% indiscutable.

### C. Couche Relationnelle (Knowledge Graph)
*   **Neo4j** : Stocke les relations entre les œuvres, les studios, les auteurs et les micro-tags générés par LLM.
*   **Utilité** : Permet à l'IA d'expliquer *pourquoi* deux œuvres se ressemblent (ex: "Même studio de production").

## 2. Modes de Jeu & Innovation

### Solo
1.  **Animetix Classic** : Recherche sémantique pure. Score de 0 à 100 basé sur la distance cosinus.
2.  **Emoji Decode** : L'IA traduit un synopsis en une série de 5 emojis complexes.
3.  **Animinator (Oracle)** : L'utilisateur pose des questions à l'IA. L'IA utilise son système d'agent pour vérifier ses connaissances avant de répondre.
4.  **Akinetix (Devin)** : L'inverse. L'IA pose des questions stratégiques pour réduire le cercle des candidats dans ChromaDB.
5.  **Le Paradoxe** : Test de logique. Trouver l'intrus parmi 3 titres grâce à l'analyse thématique du LLM.

### Social (Multijoueur)
*   **WebSockets** : Utilisation de **Django Channels** pour des salons de jeux instantanés.
*   **Undercover Online** : L'IA trouve deux termes sémantiquement proches pour tromper les joueurs.

### Créativité
*   **La Forge de l'Imaginaire** : Fusion de deux univers. Utilise un LLM pour le scénario et le modèle **Flux.1-schnell** pour générer une illustration unique.

## 3. Flux de Données & Intégration

L'architecture est conçue pour être "data-driven" avec une boucle de rétroaction continue entre l'utilisateur et les modèles d'IA.

### A. Cycle d'Ingestion (Data Pipeline)
1.  **Ingestion** : Dagster exécute des scripts d'ingestion (AniList/Jikan) stockant les données brutes dans `data/raw`.
2.  **Raffinement & Filtrage** : Les données sont nettoyées et filtrées selon des critères de popularité/qualité.
3.  **Vectorisation** : Les entités (animes, mangas, personnages) sont transformées en embeddings et stockées dans **ChromaDB**.
4.  **Génération de Graphe** : Les relations sont injectées dans **Neo4j** pour permettre le raisonnement logique.

### B. Boucle de Rétroaction RLHF (Backend -> ML)
Cette boucle permet d'améliorer l'IA en fonction des interactions réelles :
1.  **Collecte (Backend)** : Django enregistre les feedbacks via `AIFeedback` et les sessions de jeu via `GameplaySession`.
2.  **Export (Port/Adapter)** : La commande Django `export_rlhf_data` (appelée par Dagster) transforme ces entrées SQL en fichiers JSON.
3.  **Préparation TRL** : L'asset Dagster `trl_ready_dataset` convertit les feedbacks en paires *Chosen/Rejected* (DPO format).
4.  **Fine-Tuning** : Les modèles sont ré-entraînés sur ces nouvelles données pour affiner leur comportement "Otaku".

### C. Inférence & Consommation (Brain API)
- Le backend communique avec la **Brain API** pour toutes les tâches de génération.
- La Brain API utilise les index ChromaDB et Neo4j mis à jour par le pipeline Dagster pour ses recherches RAG.

## 4. Organisation du Projet

Le projet suit une structure organisée pour respecter les principes de l'**Architecture Hexagonale** et faciliter la maintenance :

- **`core/`** : Le **Domaine**. Contient la logique métier pure et l'intelligence centrale (`brain.py`). Ce dossier est indépendant des frameworks externes.
- **`backend/`** : L'**Adapteur Driving**. Application Django gérant l'interface utilisateur, les APIs et la logique de jeu.
- **`pipeline/`** : L'**Adapteur Infrastructure**. Orchestration Dagster pour l'ingestion et le traitement des données.
- **`infra/`** : Configurations système et déploiement (`supervisord`, `prometheus`, `docker`).
- **`scripts/`** : Utilitaires de lancement, de maintenance et d'entraînement.
- **`data/`** : Stockage des données à différents stades (brut, processe, modèles, vecteurs).
- **`logs/`** : Centralisation des journaux d'exécution.

## 5. Infrastructure & MLOps

*   **Pipeline de Données** : Orchestrée par **Dagster**. Gère l'ingestion incrémentale (AniList, IGDB, TMDB).
*   **MLOps & RLHF** : Collecte des feedbacks utilisateurs (AIFeedback) pour créer des datasets d'entraînement futurs.
*   **Automatisation Asynchrone** : **Celery + Redis** déportent les calculs lourds (génération d'images) hors du cycle de requête HTTP.
*   **Observabilité** : 
    *   **Prometheus** : Collecte des métriques de performance.
    *   **Grafana** : Tableaux de bord de santé du système.
    *   **Sentry** : Monitoring des erreurs en temps réel.

## 4. Interprétabilité
*   **Visualisation 3D** : Utilisation de **UMAP** pour projeter l'espace latent en 3 dimensions. Cela permet de visualiser les clusters thématiques (ex: le groupe des animes de sport vs les romances).

---
*Document produit pour Animetix - Architecture Version 2.0*