# Architecture de l'application Documentation du conditionnement et de l'architecture du chatbot RAG (Retrieval-Augmented Generation). --- ## Vue d'ensemble Application Flask de **chatbot documentaire** qui répond aux questions à partir du contenu du wiki Intersel. Le flux repose sur : 1. **Indexation** : scraping du wiki → découpage en chunks → embeddings → index FAISS 2. **Requête** : question utilisateur → recherche hybride (FAISS + BM25 + rerank) → contexte + LLM → réponse --- ## Composants principaux | Composant | Rôle | Fichiers / modules | |-----------|------|--------------------| | **Scraping** | Récupération des pages wiki (Dokuwiki), détection des changements par hash | `src/agent_ai/scraping.py`, `src/agent_ai/auth.py` | | **Chunking** | Découpage sémantique du texte (phrases, overlap) | `src/agent_ai/chunking.py` | | **Pipeline d'indexation** | Orchestration : scrape → chunks → embeddings → FAISS | `src/utils/processing.py` | | **State** | État global (chunks, index FAISS, modèle d'embedding, mémoire) | `src/service/state.py` | | **Recherche hybride** | FAISS + BM25 + MMR (diversité) + cross-encoder (rerank) | `src/service/embedding_service.py` | | **Mémoire longue durée** | Stockage des Q/R passées dans un index FAISS dédié | `src/service/memory_service.py` | | **QA / LLM** | Vérification sécurité, construction du prompt, appel Mistral (Scaleway) | `src/service/qa_service.py` | | **API** | Routes Flask (chat, health, status, trigger-indexation) | `src/app.py`, `src/api/*.py` | --- ## Flux de données ### 1. Indexation (pipeline) ``` wiki.intersel.fr (Dokuwiki) │ ▼ scrape_pages() — session authentifiée, crawl limité (voir Choix_techniques.md) │ raw_pages.json / page_hashes.json / urls.json │ ▼ update_chunks() — clean_text + semantic_chunking │ All_chunks.json (chunk_id, text, url, word_count, token_count) │ ▼ build_and_save_index() — SentenceTransformer + FAISS (cosine) │ faiss_index.index │ ▼ pipeline_status.json (last_run, duration, chunk_count, scraping_stats) ``` - **Première indexation** : pas de `All_chunks.json` ni `faiss_index.index` → scrape complet, chunking, construction de l’index. - **Mise à jour incrémentale** : fichiers présents → scrape, mise à jour des pages modifiées (hash), reconstruction de l’index. ### 2. Réponse à une question (QA) ``` Question utilisateur (POST /qa_chain) │ ▼ quote_keywords() — spaCy, mise entre guillemets des noms/entités │ ▼ detect_topic_smart() — similarité avec l’historique de chat │ ▼ _is_safe_query() — LLM Scaleway (sécurité) │ ▼ hybrid_search() — FAISS + BM25 + MMR + cross-encoder → top N chunks │ ▼ Contexte = mémoire longue durée (topic) + chat récent (topic) + chunks │ ▼ call_scaleway_llama3() — Mistral, réponse factuelle │ ▼ save_memory_entry() — sauvegarde Q/R en mémoire longue durée │ Réponse + sources (chunk_id + URL) ``` En cas d’erreur (ou contexte vide), **fallback SerpAPI** (recherche Google + résumé LLM). --- ## Fichiers de données (répertoire `src/data/`) | Fichier | Description | |---------|-------------| | `urls.json` | Liste des URLs wiki connues (crawl) | | `page_hashes.json` | Hash MD5 du contenu par URL (détection des modifications) | | `raw_pages.json` | Contenu brut des pages (url, text) | | `All_chunks.json` | Chunks avec métadonnées (chunk_id, text, url, etc.) | | `faiss_index.index` | Index FAISS (vecteurs normalisés, similarité cosinus) | | `pipeline_status.json` | Dernier run du pipeline (durée, chunk_count, erreurs, scraping_stats) | | `memory_chunks.json` | Entrées de la mémoire longue durée (Q/R) | | `faiss_memory_index.index` | Index FAISS pour la mémoire longue durée | --- ## Démarrage et santé - **Démarrage** : `auto_login()` (wiki), `init_memory()`, puis si `ready=False` → exécution du pipeline d’indexation et rechargement du state. - **Scheduler** : toutes les 24 h, `run_full_update()` (pipeline + rechargement du state). - **Healthcheck** : `GET /api/health` → 200 si chunks et index présents et valides, 503 sinon. - **Statut** : `GET /api/status` → détails du dernier pipeline (durée, chunks, scraping_stats). - **Indexation manuelle** : `POST /api/trigger-indexation` → lance le pipeline et recharge le state. --- ## Dépendances externes - **Wiki** : authentification (WIKI_USERNAME, WIKI_PASSWORD) pour le scraping. - **Scaleway** : API Mistral (SCW_API_KEY, SCW_ENDPOINT, SCW_MODEL) pour génération et filtre de sécurité. - **SerpAPI** (optionnel) : fallback en cas d’erreur ou de contexte vide (SERPAPI_API_KEY). Les choix techniques (limites, modèles, seuils) sont décrits dans **Choix_techniques.md**.