# Choix techniques et limites Documentation des décisions implicites, limites et paramètres importants de l’application. --- ## Scraping wiki ### Limite d’URLs : 100 max - **Où** : `src/agent_ai/scraping.py`, constante `MAX_URLS_TO_SCRAPE = 100`. - **Effet** : - Le crawl s’arrête après avoir **visité** au plus 100 URLs (pages découvertes en suivant les liens depuis la page d’accueil). - La liste finale `all_urls` (anciennes URLs + URLs du crawl) est **tronquée à 100** avant d’appeler `fetch_all_pages_content`. - **Raison** : limiter le temps de scraping, la charge sur le wiki et la taille des données (chunks, index). - **Modifier** : changer la valeur de `MAX_URLS_TO_SCRAPE` dans `scraping.py` (et éventuellement documenter ici). ### URLs prises en compte Une URL est valide si (`is_valid_wiki_url`) : - Domaine `wiki.intersel.fr` - Pas de `do=` dans la query (exclut les pages d’édition) - Pas d’extension `.jpg`, `.png`, `.pdf`, `.docx`, `.xlsx` - Pas de `#` dans l’URL ### Authentification - Connexion au wiki via formulaire (token CSRF), session HTTP persistante. - Identifiants dans `.env` : `WIKI_USERNAME`, `WIKI_PASSWORD`. --- ## Indexation (chunks, FAISS) ### Modèles - **Embeddings** : `sentence-transformers/all-mpnet-base-v2` (processing + state). - **Cross-encoder** (rerank) : `cross-encoder/ms-marco-MiniLM-L-6-v2` (state). - **Chunking** : découpage sémantique par phrases avec overlap (voir `src/agent_ai/chunking.py`). ### Première indexation vs mise à jour incrémentale - **Première indexation** : aucun fichier `All_chunks.json` ou `faiss_index.index` → scrape (limité à 100 URLs), chunking complet, construction de l’index. - **Mise à jour incrémentale** : fichiers présents → scrape, mise à jour uniquement des pages dont le hash a changé, puis reconstruction de l’index. --- ## QA (questions / réponses) ### LLM - **API** : Scaleway (compatible OpenAI), modèle par défaut `mistral-small-3.2-24b-instruct-2506`. - **Variables** : `SCW_API_KEY`, `SCW_ENDPOINT` (optionnel), `SCW_MODEL`. ### Recherche hybride - **FAISS** : top 200 candidats (paramètre `top_k_candidates`). - **BM25** : pondération selon la longueur de la requête (courte → 0.7, etc.). - **MMR** : diversité des chunks (éviter le doublon), lambda 0.7. - **Cross-encoder** : rerank des passages, score final = 0.4 × hybride + 0.6 × cross-encoder. - **Top final** : 20 chunks envoyés au LLM. ### Topic / mémoire - **Détection de topic** : similarité (embedding) avec l’historique de chat ; seuil 0.7 pour réutiliser un topic existant. - **Mémoire longue durée** : Q/R sauvegardées dans un index FAISS séparé ; récupération des plus pertinentes (top_k=20) puis filtrage par topic pour le contexte. ### Sécurité - Chaque question passe par un **filtre de sécurité** (LLM) : refus si contenu sensible ou malveillant (mot de passe, carte bancaire, hacking, etc.). ### Fallback - Si erreur ou contexte vide : recherche **SerpAPI** (Google) + résumé par le LLM. Nécessite `SERPAPI_API_KEY` (optionnel). --- ## API et configuration ### Routes documentées - `GET /api/health` : santé (chunks + index chargés) → 200 ou 503. - `GET /api/status` : statut détaillé du pipeline (dernier run, durée, chunk_count, scraping_stats). - `POST /api/trigger-indexation` : lancement manuel du pipeline + rechargement du state. ### Limites côté app - **Taille max payload** : 16 Mo (`MAX_CONTENT_LENGTH`). - **Longueur max message chat** : 2000 caractères (`CHAT_MAX_CHARS`). - **Anti-spam** : message vide, répétition de caractères (≥ 50), trop d’URLs (≥ 5) → rejet. --- ## Scheduler - **Intervalle** : 24 h (APScheduler, `run_full_update`). - **Verrou** : une seule exécution du pipeline à la fois (`update_lock`). --- ## Résumé des constantes à connaître | Élément | Valeur / emplacement | |--------|----------------------| | URLs max à scraper | 100 — `scraping.py` → `MAX_URLS_TO_SCRAPE` | | Workers scraping | 2 — `ThreadPoolExecutor(max_workers=2)` | | Top candidats recherche | 200 — `embedding_service.py` → `top_k_candidates` | | Top chunks final | 20 — `top_k_final` | | Seuil topic | 0.7 — `qa_service.py` → `detect_topic_smart` | | MMR lambda | 0.7 — `embedding_service.py` → `mmr_lambda` | | Intervalle scheduler | 24 h — `app.py` → `scheduler.add_job(..., hours=24)` | Pour l’architecture globale et le conditionnement de l’application, voir **Architecture.md**.