Déploiement PolyglotRAG via notebook Colab

.dockerignore

@@ -0,0 +1,16 @@
+.git/
+.github/
+.venv/
+venv/
+__pycache__/
+**/__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.env
+data/
+*.sqlite3
+*.ipynb_checkpoints/
+PolyglotRAG_Deploy_HuggingFace.ipynb
+README_dev_notes.md

.env.example

@@ -0,0 +1,55 @@
+# === PolyglotRAG — variables d'environnement ===
+# Copiez ce fichier en ".env" en local, ou déclarez ces clés en tant que
+# "Secrets"/"Variables" du Space Hugging Face (jamais en clair dans le code).
+
+# Un seul jeton nécessaire : https://huggingface.co/settings/tokens
+# Scopes requis : "Make calls to Inference Providers" (+ "Write" si vous
+# poussez/mettez à jour le dataset privé depuis le Space lui-même).
+HF_TOKEN=hf_xxx_votre_jeton_ici
+
+# Dataset privé Hugging Face contenant l'index (chunks.parquet + manifest.json)
+# Exemple : "mon-compte/polyglot-rag-index"
+HF_DATASET_REPO=
+
+# Modèle génératif — DeepSeek-V4.1-Flash servi via le routeur Inference
+# Providers. ":fastest" laisse HF choisir automatiquement le provider actif
+# (Novita à ce jour) sans changer le code applicatif.
+LLM_MODEL=deepseek-ai/DeepSeek-V4.1-Flash:fastest
+LLM_TEMPERATURE=0.2
+LLM_MAX_TOKENS=1024
+
+# Modèle d'embeddings multilingue partagé
+EMBEDDING_MODEL=BAAI/bge-m3
+EMBEDDING_DIM=1024
+USE_QUERY_PASSAGE_PREFIX=false
+
+# Recherche hybride
+TOP_K_RETRIEVE=15
+# Nombre de passages réellement envoyés au LLM : volontairement limité à 2
+# (latence/coût réduits, contexte plus dense). Augmentez si nécessaire.
+TOP_K_FINAL=2
+SAME_LANGUAGE_BONUS=0.04
+MIN_CONFIDENCE_SCORE=0.28
+
+# Index vectoriel : recherche approximative (ANN) par défaut.
+# "hnsw" = FAISS IndexHNSWFlat (rapide, pas d'entraînement requis)
+# "flat" = recherche exacte (IndexFlatIP), utile pour comparer la qualité
+ANN_INDEX_TYPE=hnsw
+ANN_HNSW_M=32
+ANN_EF_SEARCH=64
+
+# Cache (réponses complètes + embeddings de requêtes)
+ENABLE_CACHE=true
+CACHE_TTL_SECONDS=600
+CACHE_MAX_SIZE=512
+
+# Chunking
+CHUNK_SIZE_TOKENS=350
+CHUNK_OVERLAP_TOKENS=60
+
+# Mot de passe de l'onglet Admin (laisser vide = accès libre, déconseillé en prod)
+ADMIN_PASSWORD=
+
+# Stockage local (cache / dev)
+LOCAL_INDEX_DIR=data/index
+METRICS_DB_PATH=data/metrics.sqlite3

.gitignore

@@ -0,0 +1,14 @@
+.venv/
+venv/
+__pycache__/
+**/__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.mypy_cache/
+.env
+data/*
+!data/.gitkeep
+*.sqlite3
+.ipynb_checkpoints/
+.DS_Store

Dockerfile

@@ -0,0 +1,37 @@
+# PolyglotRAG — image Docker de production.
+# Compatible : exécution locale (docker run / docker compose) ET
+# Hugging Face Spaces en SDK "docker" (README.md: sdk: docker, app_port: 7860).
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PORT=7860
+
+WORKDIR /app
+
+# Dépendances système minimales : libgomp1 pour faiss-cpu, build-essential
+# pour compiler les rares roues non pré-buildées (arm64 notamment).
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential \
+        libgomp1 \
+        curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+# Hugging Face Spaces (SDK docker) exige un utilisateur non-root (UID 1000).
+RUN useradd -m -u 1000 appuser \
+    && mkdir -p /app/data \
+    && chown -R appuser:appuser /app
+USER appuser
+
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+    CMD curl -fsS "http://127.0.0.1:${PORT}/" || exit 1
+
+CMD ["python", "app.py"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PolyglotRAG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,10 +1,291 @@
 ---
-title: Polyglot Rag
-emoji: 🏢
-colorFrom: green
-colorTo: pink
+title: PolyglotRAG
+emoji: 🌍
+colorFrom: blue
+colorTo: yellow
 sdk: docker
+app_port: 7860
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🌍 PolyglotRAG
+
+Assistant documentaire multilingue et **cross-lingue** : posez une question en
+anglais, français, russe, espagnol, arabe ou portugais, et obtenez une réponse
+sourcée — même si le document pertinent est rédigé dans une **autre** langue
+que la question.
+
+> Exemple : une question posée en **russe** retrouve un règlement rédigé en
+> **français** et un rapport en **anglais**, puis PolyglotRAG répond en russe
+> en citant les documents originaux — sans jamais traduire le corpus au
+> préalable.
+
+Propulsé par **DeepSeek-V4.1-Flash** (génération) et **BAAI/bge-m3**
+(embeddings multilingues partagés), les deux via le routeur *Inference
+Providers* de Hugging Face — **un seul jeton d'API** suffit pour tout le
+projet.
+
+---
+
+## Sommaire
+
+- [Fonctionnalités](#fonctionnalités)
+- [Architecture](#architecture)
+- [Optimisations de performance](#optimisations-de-performance)
+- [Démarrage rapide (local, sans Docker)](#démarrage-rapide-local-sans-docker)
+- [Docker](#docker)
+- [Déploiement sur Hugging Face Spaces](#déploiement-sur-hugging-face-spaces)
+- [Structure du dépôt](#structure-du-dépôt)
+- [Configuration](#configuration)
+- [Ingestion de vos propres documents](#ingestion-de-vos-propres-documents)
+- [Tests](#tests)
+- [Choix d'architecture assumés](#choix-darchitecture-assumés)
+- [Évolutions possibles](#évolutions-possibles)
+
+## Fonctionnalités
+
+- 🔎 Détection automatique de la langue de la question (hors-ligne, `lingua`).
+- 📥 Ingestion PDF, DOCX, Markdown, HTML, CSV, avec langue/fichier/page/titre
+  conservés par chunk.
+- 🌐 Recherche **cross-lingue** dans un espace sémantique multilingue partagé
+  (BGE-M3), avec 3 modes : global, filtré par langue, priorité locale.
+- 🧠 Génération strictement source-grounded (mode strict / abstention si le
+  score de confiance est trop faible).
+- 🈯 Interface **RTL** correcte pour l'arabe.
+- 📚 Citations systématiques : fichier, langue, page, score.
+- 📊 Page **Admin** : métriques du RAG (volume, latence, langues, taux
+  d'abstention, historique des requêtes).
+- 🏗️ Page **Architecture** : schéma complet du pipeline.
+- 🔐 Stockage vectoriel dans un **dataset privé Hugging Face** (aucun service
+  tiers à héberger).
+- ⚡ **Cache** réponses + embeddings de requêtes, **recherche approximative
+  (ANN / FAISS-HNSW)** et **top-k final limité à 2** — voir
+  [Optimisations de performance](#optimisations-de-performance).
+- 🐳 **Dockerfile** fourni (image de production, utilisateur non-root,
+  healthcheck) — exécution locale ou Space Hugging Face en SDK Docker.
+
+## Architecture
+
+Voir l'onglet **Architecture** de l'application pour le schéma interactif.
+Résumé :
+
+```
+Documents multilingues (knowledge_base/<lang>/*)
+        │
+        ▼
+Extraction PDF / DOCX / MD / HTML / CSV
+        │
+        ▼
+Détection langue + métadonnées (fichier, page, titre, sens RTL/LTR)
+        │
+        ▼
+Chunking adapté à la langue (découpage par phrases + recouvrement)
+        │
+        ▼
+Embeddings multilingues partagés — BAAI/bge-m3 (HF Inference Providers)
+        │
+        ▼
+Dataset privé Hugging Face (Parquet) ──► chargé en FAISS au démarrage
+        │
+        ▼
+Question utilisateur ──► détection de langue ──► recherche ANN cross-lingue (top-15, FAISS-HNSW)
+        │
+        ▼
+Bonus langue + reranking (top-2 final) ──► mode strict (seuil de confiance)
+        │
+        ▼
+DeepSeek-V4.1-Flash (routeur HF) ──► réponse + citations + score
+        │
+        ▼
+Cache réponse (TTL) ──► une question identique reposée pendant la fenêtre
+                         de cache ne refait ni la recherche, ni l'appel LLM
+```
+
+## Optimisations de performance
+
+Trois optimisations sont actives par défaut (`config.py` / `.env.example`) :
+
+| Optimisation | Où | Détail |
+|---|---|---|
+| **Cache** | `core/optimization/cache.py`, `core/pipeline.py` | Cache à expiration (TTL, 10 min par défaut) sur (1) les embeddings de questions déjà posées et (2) les réponses complètes pour une question strictement identique (même langue de réponse, même filtre). Désactivable via `ENABLE_CACHE=false`. |
+| **Recherche approximative (ANN)** | `core/retrieval/vector_store.py` | Index `FAISS IndexHNSWFlat` par défaut au lieu d'une recherche exacte (`IndexFlatIP`) : bien plus rapide dès que le corpus grossit, sans étape d'entraînement. Réglable via `ANN_INDEX_TYPE` (`hnsw`/`flat`), `ANN_HNSW_M`, `ANN_EF_SEARCH`. |
+| **Top-k final réduit** | `config.py` (`TOP_K_FINAL=2`) | Seuls les **2 meilleurs passages** (après bonus de langue et reranking) sont envoyés au LLM — moins de tokens de contexte, réponse plus rapide et moins coûteuse. `TOP_K_RETRIEVE=15` reste le pool de candidats initial avant ce filtrage final. |
+
+L'onglet **Admin** affiche en direct l'état du cache (taille/capacité) et le
+type d'index vectoriel actif, pour vérifier que ces optimisations tournent
+bien en production.
+
+## Démarrage rapide (local, sans Docker)
+
+```bash
+git clone <votre-fork-ou-dossier> polyglot-rag
+cd polyglot-rag
+python -m venv .venv && source .venv/bin/activate   # Windows : .venv\Scripts\activate
+pip install -r requirements.txt
+cp .env.example .env
+# Éditez .env : renseignez HF_TOKEN (https://huggingface.co/settings/tokens)
+
+# 1. Ingestion des documents d'exemple (ou des vôtres) -> index local
+python scripts/ingest.py --no-push
+
+# 2. Lancement de l'application
+python app.py
+```
+
+L'application s'ouvre sur `http://localhost:7860` avec les 3 onglets
+Chat / Architecture / Admin.
+
+## Docker
+
+Image de production fournie (utilisateur non-root UID 1000, healthcheck,
+compatible Hugging Face Spaces en SDK Docker).
+
+```bash
+cp .env.example .env   # renseignez HF_TOKEN au minimum
+
+# Construction + lancement
+docker compose up --build
+# ou, sans docker compose :
+docker build -t polyglot-rag .
+docker run --rm -p 7860:7860 --env-file .env -v "$(pwd)/data:/app/data" polyglot-rag
+```
+
+Pensez à ingérer vos documents avant (ou après) le premier démarrage :
+
+```bash
+docker compose run --rm polyglot-rag python scripts/ingest.py --no-push
+```
+
+L'application est alors disponible sur `http://localhost:7860`.
+
+## Déploiement sur Hugging Face Spaces
+
+Le Space est un **Space Docker** : `README.md` déclare `sdk: docker` et
+`app_port: 7860`, et Hugging Face construit directement le `Dockerfile`
+fourni à la racine — aucune configuration supplémentaire n'est nécessaire
+côté Space.
+
+**Option recommandée : notebook Colab fourni**
+(`PolyglotRAG_Deploy_HuggingFace.ipynb`). Il automatise tout :
+
+1. Installation des dépendances.
+2. Saisie sécurisée de votre `HF_TOKEN` (jamais affiché en clair).
+3. Création du dataset privé + ingestion des documents.
+4. Publication du dataset privé sur le Hub.
+5. Création du Space en **SDK Docker** + injection du token en secret.
+6. Publication du code de l'application (dont le `Dockerfile`).
+7. Affichage de l'URL finale du Space (build Docker déclenché automatiquement
+   par Hugging Face).
+
+**Option manuelle**, en ligne de commande :
+
+```bash
+python scripts/ingest.py                       # pousse l'index vers HF_DATASET_REPO
+hf repos create <votre-compte>/polyglot-rag --repo-type space --space_sdk docker
+huggingface-cli upload <votre-compte>/polyglot-rag . --repo-type space
+# Puis, dans les Settings du Space : ajoutez les secrets HF_TOKEN et HF_DATASET_REPO
+```
+
+## Structure du dépôt
+
+```
+polyglot-rag/
+├── app.py                        # Point d'entrée Gradio (Chat / Architecture / Admin)
+├── config.py                     # Configuration centralisée (variables d'env)
+├── Dockerfile                     # Image de production (Space Docker + usage local)
+├── docker-compose.yml             # Confort de développement local
+├── .dockerignore
+├── requirements.txt
+├── .env.example
+├── knowledge_base/                # Documents d'exemple (6 langues) — à remplacer par les vôtres
+│   ├── en/ fr/ ru/ es/ ar/ pt/
+├── core/
+│   ├── ingestion/                 # loaders, détection de langue, chunking, indexeur
+│   ├── retrieval/                 # embeddings, FAISS (ANN), recherche cross-lingue
+│   ├── generation/                 # prompts, appel LLM
+│   ├── optimization/               # cache réponses + embeddings (TTL)
+│   ├── pipeline.py                 # orchestration retrieval + génération + cache + métriques
+│   ├── metrics/                   # journalisation SQLite pour l'Admin
+│   ├── ui/                        # onglets Gradio (Chat, Admin, Architecture)
+│   └── assets/architecture.svg    # schéma d'architecture
+├── scripts/ingest.py               # CLI d'ingestion / publication du dataset
+├── tests/                          # pytest (aucun test ne fait d'appel réseau)
+├── data/                           # cache local (index, métriques) — gitignored
+└── PolyglotRAG_Deploy_HuggingFace.ipynb
+```
+
+## Configuration
+
+Toutes les options sont documentées dans `.env.example`. Point clé :
+**un seul jeton, `HF_TOKEN`**, avec le scope *"Make calls to Inference
+Providers"* (+ *"Write"* si le Space doit aussi pousser/rafraîchir le
+dataset). Créez-le sur
+[huggingface.co/settings/tokens](https://huggingface.co/settings/tokens).
+
+| Variable | Rôle | Défaut |
+|---|---|---|
+| `HF_TOKEN` | Authentification unique (LLM, embeddings, dataset) | — (obligatoire) |
+| `HF_DATASET_REPO` | Dataset privé contenant l'index | — |
+| `LLM_MODEL` | Modèle génératif | `deepseek-ai/DeepSeek-V4.1-Flash:fastest` |
+| `EMBEDDING_MODEL` | Modèle d'embeddings | `BAAI/bge-m3` |
+| `TOP_K_FINAL` | Passages envoyés au LLM | `2` |
+| `ANN_INDEX_TYPE` | `hnsw` (approximatif) ou `flat` (exact) | `hnsw` |
+| `ENABLE_CACHE` | Cache réponses + embeddings de requêtes | `true` |
+| `CACHE_TTL_SECONDS` | Durée de vie du cache | `600` |
+| `MIN_CONFIDENCE_SCORE` | Seuil d'abstention (mode strict) | `0.28` |
+| `ADMIN_PASSWORD` | Protège l'onglet Admin | vide (accès libre) |
+
+## Ingestion de vos propres documents
+
+1. Placez vos fichiers dans `knowledge_base/<code_langue>/` (`en`, `fr`, `ru`,
+   `es`, `ar`, `pt`) — formats supportés : `.pdf`, `.docx`, `.md`, `.html`,
+   `.csv`.
+2. Lancez `python scripts/ingest.py` (pousse automatiquement vers
+   `HF_DATASET_REPO` si défini).
+3. Redémarrez le Space (ou rechargez la page) : l'index est reconstruit au
+   démarrage à partir du dataset privé.
+
+⚠️ Les PDF scannés sans couche texte ne sont pas encore océrisés
+automatiquement — le loader signale les pages concernées
+(`[PAGE SANS TEXTE EXTRACTIBLE — OCR REQUIS]`) plutôt que d'indexer du vide.
+
+## Tests
+
+```bash
+pip install pytest
+pytest
+```
+
+Tous les tests s'exécutent **hors-ligne** (un garde-fou dans
+`tests/conftest.py` fait échouer volontairement tout test qui tenterait un
+appel réseau réel vers l'API d'embeddings).
+
+## Choix d'architecture assumés
+
+- **Pas de traduction systématique du corpus.** Chaque chunk garde son
+  texte et sa langue d'origine ; seule la recherche passe par un espace
+  d'embeddings partagé. La traduction n'intervient jamais côté indexation.
+- **FAISS en mémoire plutôt qu'un service Qdrant externe.** Le dataset privé
+  Hugging Face joue le rôle de stockage persistant (Parquet) ; l'index est
+  reconstruit en mémoire au démarrage du Space. Pour un corpus de quelques
+  dizaines de milliers de chunks, c'est largement suffisant, et cela évite
+  une seconde dépendance opérationnelle (donc une seconde clé d'API) — cohérent
+  avec la contrainte « un seul jeton Hugging Face ».
+- **DeepSeek-V4.1-Flash via le routeur *Inference Providers*.** Le modèle
+  n'est pas déployé/hébergé par ce projet : il est appelé via
+  `https://router.huggingface.co`, qui route vers un provider tiers (Novita
+  à ce jour) tout en facturant sur votre compte Hugging Face. Le
+  qualificatif `:fastest` sur `LLM_MODEL` s'adapte automatiquement si le
+  provider change.
+
+## Évolutions possibles
+
+- Reranking cross-encoder dédié (au lieu du bonus de score actuel).
+- Snapshot périodique de la base de métriques vers le dataset HF (persistance
+  au-delà du cycle de vie du Space).
+- Agents spécialisés (routeur de langue, agent de récupération cross-lingue,
+  agent terminologie/glossaire métier, agent qualité) pour une architecture
+  de type Corrective RAG multi-agent, comme décrit dans le document de
+  cadrage du projet.
+- OCR automatique pour les PDF scannés.

app.py

@@ -0,0 +1,66 @@
+"""
+PolyglotRAG — assistant documentaire multilingue cross-lingue.
+Point d'entrée de l'application Gradio (compatible Hugging Face Spaces,
+SDK "gradio").
+
+Onglets :
+  - Chat          : interface de question/réponse multilingue avec citations.
+  - Architecture  : schéma du pipeline complet.
+  - Admin         : métriques du RAG (volume, latence, langues, abstention).
+"""
+from __future__ import annotations
+
+import gradio as gr
+
+from core.ui.admin_tab import build_admin_tab
+from core.ui.architecture_tab import build_architecture_tab
+from core.ui.chat_tab import build_chat_tab
+from core.ui.theme import CUSTOM_CSS
+from config import settings
+
+HEADER_HTML = """
+<div id="pg-header">
+  <h1>🌍 PolyglotRAG</h1>
+  <p>Assistant documentaire multilingue cross-lingue — EN · FR · RU · ES · AR (RTL) · PT ·
+  propulsé par DeepSeek-V4.1-Flash</p>
+</div>
+"""
+
+
+def build_app() -> gr.Blocks:
+    with gr.Blocks(
+        title="PolyglotRAG",
+        css=CUSTOM_CSS,
+        theme=gr.themes.Soft(primary_hue="blue", neutral_hue="slate"),
+    ) as demo:
+        gr.HTML(HEADER_HTML)
+
+        config_errors = settings.validate()
+        if config_errors:
+            gr.Markdown(
+                "⚠️ **Configuration incomplète** : " + " ".join(config_errors)
+            )
+
+        with gr.Tabs():
+            with gr.TabItem("💬 Chat"):
+                build_chat_tab()
+            with gr.TabItem("🏗️ Architecture"):
+                build_architecture_tab()
+            with gr.TabItem("🔐 Admin"):
+                build_admin_tab()
+
+    return demo
+
+
+demo = build_app()
+
+if __name__ == "__main__":
+    import os
+
+    # 0.0.0.0 + $PORT (par défaut 7860) : fonctionne à l'identique en local,
+    # dans le conteneur Docker fourni, et sur un Hugging Face Space
+    # (SDK "gradio" ou "docker" — voir Dockerfile / README).
+    demo.queue().launch(
+        server_name="0.0.0.0",
+        server_port=int(os.environ.get("PORT", 7860)),
+    )

config.py

@@ -0,0 +1,153 @@
+"""
+Configuration centrale de PolyglotRAG.
+
+Toutes les valeurs peuvent être surchargées par des variables d'environnement
+(fichier .env en local, "Secrets"/"Variables" sur un Hugging Face Space).
+Le projet n'a besoin que d'UN seul token : HF_TOKEN (droits "Make calls to
+Inference Providers" + lecture/écriture sur le dataset privé).
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+try:
+    from dotenv import load_dotenv
+    load_dotenv()
+except ImportError:  # pragma: no cover - python-dotenv est optionnel
+    pass
+
+
+SUPPORTED_LANGUAGES: dict[str, dict[str, str]] = {
+    "en": {"name": "English", "dir": "ltr"},
+    "fr": {"name": "Français", "dir": "ltr"},
+    "ru": {"name": "Русский", "dir": "ltr"},
+    "es": {"name": "Español", "dir": "ltr"},
+    "ar": {"name": "العربية", "dir": "rtl"},
+    "pt": {"name": "Português", "dir": "ltr"},
+}
+
+
+def _bool_env(name: str, default: bool) -> bool:
+    val = os.getenv(name)
+    if val is None:
+        return default
+    return val.strip().lower() in {"1", "true", "yes", "on"}
+
+
+@dataclass
+class Settings:
+    # --- Authentification (un seul token pour tout) -----------------------
+    hf_token: str = field(default_factory=lambda: os.getenv("HF_TOKEN", ""))
+
+    # --- Modèle génératif ---------------------------------------------------
+    # Servi via le routeur "Inference Providers" de Hugging Face.
+    # ":fastest" laisse HF choisir automatiquement le meilleur provider
+    # (aujourd'hui Novita) sans jamais changer de code applicatif.
+    llm_model: str = field(
+        default_factory=lambda: os.getenv(
+            "LLM_MODEL", "deepseek-ai/DeepSeek-V4.1-Flash:fastest"
+        )
+    )
+    llm_temperature: float = field(
+        default_factory=lambda: float(os.getenv("LLM_TEMPERATURE", "0.2"))
+    )
+    llm_max_tokens: int = field(
+        default_factory=lambda: int(os.getenv("LLM_MAX_TOKENS", "1024"))
+    )
+
+    # --- Modèle d'embeddings --------------------------------------------
+    # BGE-M3 = qualité maximale, multilingue + cross-lingue natif (défaut).
+    # intfloat/multilingual-e5-base = alternative légère (variable d'env).
+    embedding_model: str = field(
+        default_factory=lambda: os.getenv("EMBEDDING_MODEL", "BAAI/bge-m3")
+    )
+    embedding_dim: int = field(
+        default_factory=lambda: int(os.getenv("EMBEDDING_DIM", "1024"))
+    )
+    use_query_passage_prefix: bool = field(
+        default_factory=lambda: _bool_env("USE_QUERY_PASSAGE_PREFIX", False)
+    )
+
+    # --- Stockage vectoriel (dataset privé Hugging Face) --------------------
+    hf_dataset_repo: str = field(
+        default_factory=lambda: os.getenv("HF_DATASET_REPO", "")
+    )
+    local_index_dir: str = field(
+        default_factory=lambda: os.getenv("LOCAL_INDEX_DIR", "data/index")
+    )
+
+    # --- Chunking -----------------------------------------------------------
+    chunk_size_tokens: int = field(
+        default_factory=lambda: int(os.getenv("CHUNK_SIZE_TOKENS", "350"))
+    )
+    chunk_overlap_tokens: int = field(
+        default_factory=lambda: int(os.getenv("CHUNK_OVERLAP_TOKENS", "60"))
+    )
+
+    # --- Recherche hybride ----------------------------------------------
+    top_k_retrieve: int = field(
+        default_factory=lambda: int(os.getenv("TOP_K_RETRIEVE", "15"))
+    )
+    # Volontairement bas par défaut : moins de passages envoyés au LLM ->
+    # latence et coût réduits, contexte plus dense. Augmentez si votre
+    # corpus a besoin de plus de passages pour couvrir une même réponse.
+    top_k_final: int = field(
+        default_factory=lambda: int(os.getenv("TOP_K_FINAL", "2"))
+    )
+    same_language_bonus: float = field(
+        default_factory=lambda: float(os.getenv("SAME_LANGUAGE_BONUS", "0.04"))
+    )
+    min_confidence_score: float = field(
+        default_factory=lambda: float(os.getenv("MIN_CONFIDENCE_SCORE", "0.28"))
+    )
+
+    # --- Index vectoriel : recherche exacte ou approximative (ANN) ---------
+    # "hnsw" (par défaut) = FAISS IndexHNSWFlat, approximatif mais bien plus
+    # rapide sur un grand corpus, sans étape d'entraînement (contrairement à
+    # IVF). "flat" = recherche exacte (IndexFlatIP), utile pour un tout petit
+    # corpus de test ou pour comparer la qualité du retrieval.
+    ann_index_type: str = field(
+        default_factory=lambda: os.getenv("ANN_INDEX_TYPE", "hnsw")
+    )
+    ann_hnsw_m: int = field(
+        default_factory=lambda: int(os.getenv("ANN_HNSW_M", "32"))
+    )
+    ann_ef_search: int = field(
+        default_factory=lambda: int(os.getenv("ANN_EF_SEARCH", "64"))
+    )
+
+    # --- Cache (réponses + embeddings de requêtes) --------------------------
+    enable_cache: bool = field(
+        default_factory=lambda: _bool_env("ENABLE_CACHE", True)
+    )
+    cache_ttl_seconds: int = field(
+        default_factory=lambda: int(os.getenv("CACHE_TTL_SECONDS", "600"))
+    )
+    cache_max_size: int = field(
+        default_factory=lambda: int(os.getenv("CACHE_MAX_SIZE", "512"))
+    )
+
+    # --- Journalisation / métriques ---------------------------------------
+    metrics_db_path: str = field(
+        default_factory=lambda: os.getenv("METRICS_DB_PATH", "data/metrics.sqlite3")
+    )
+
+    # --- Admin ---------------------------------------------------------------
+    admin_password: str = field(
+        default_factory=lambda: os.getenv("ADMIN_PASSWORD", "")
+    )
+
+    def validate(self) -> list[str]:
+        errors = []
+        if not self.hf_token:
+            errors.append(
+                "HF_TOKEN manquant : créez un token sur "
+                "https://huggingface.co/settings/tokens avec le scope "
+                "'Make calls to Inference Providers' (+ 'Write' si vous "
+                "poussez un dataset)."
+            )
+        return errors
+
+
+settings = Settings()

core/__init__.py

@@ -0,0 +1,2 @@
+"""PolyglotRAG — assistant documentaire multilingue cross-lingue."""
+__version__ = "1.0.0"

core/generation/answer_generator.py

@@ -0,0 +1,77 @@
+"""
+Appel du LLM génératif — DeepSeek-V4.1-Flash — via le routeur "Inference
+Providers" de Hugging Face (https://router.huggingface.co), qui proxy
+automatiquement vers un provider tiers (Novita à ce jour) tout en
+n'exigeant qu'un seul jeton HF_TOKEN pour l'authentification et la
+facturation. Aucune autre clé d'API n'est nécessaire.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from functools import lru_cache
+
+from core.generation.prompts import build_messages, no_context_message
+from core.retrieval.hybrid_search import RetrievalResult
+from config import settings
+
+
+@dataclass
+class GenerationResult:
+    answer: str
+    used_fallback: bool
+    latency_seconds: float
+    sources: list[dict]
+
+
+@lru_cache(maxsize=1)
+def _get_client():
+    from huggingface_hub import InferenceClient
+
+    if not settings.hf_token:
+        raise RuntimeError("HF_TOKEN manquant : impossible d'appeler le LLM.")
+    return InferenceClient(api_key=settings.hf_token)
+
+
+def generate_answer(
+    question: str,
+    retrieval: RetrievalResult,
+    target_language: str,
+) -> GenerationResult:
+    start = time.perf_counter()
+
+    if not retrieval.is_sufficient:
+        return GenerationResult(
+            answer=no_context_message(target_language),
+            used_fallback=True,
+            latency_seconds=time.perf_counter() - start,
+            sources=[],
+        )
+
+    messages = build_messages(question, retrieval.hits, target_language)
+    client = _get_client()
+
+    completion = client.chat.completions.create(
+        model=settings.llm_model,
+        messages=messages,
+        temperature=settings.llm_temperature,
+        max_tokens=settings.llm_max_tokens,
+    )
+    answer = completion.choices[0].message.content
+
+    sources = [
+        {
+            "file": hit.source_file,
+            "language": hit.language,
+            "page": hit.page,
+            "score": round(hit.score, 3),
+        }
+        for hit in retrieval.hits
+    ]
+
+    return GenerationResult(
+        answer=answer,
+        used_fallback=False,
+        latency_seconds=time.perf_counter() - start,
+        sources=sources,
+    )

core/generation/prompts.py

@@ -0,0 +1,63 @@
+"""Gabarits de prompts pour la génération de réponses PolyglotRAG."""
+from __future__ import annotations
+
+from core.ingestion.language_detector import language_label
+from core.retrieval.vector_store import SearchHit
+
+SYSTEM_PROMPT_TEMPLATE = """Tu es PolyglotRAG, un assistant documentaire multilingue.
+
+Réponds UNIQUEMENT à partir des extraits de sources fournis ci-dessous.
+Ne crée jamais de faits, de chiffres, de dates ou de règles absents du contexte.
+
+Langue demandée pour la réponse : {target_language}
+
+Instructions :
+- Réponds naturellement, dans un style professionnel, dans la langue demandée ({target_language}).
+- Les documents sources peuvent être rédigés dans d'autres langues que la réponse.
+- Ne traduis jamais les noms propres, identifiants, références de contrat ou acronymes.
+- Distingue explicitement les faits établis des éléments incertains ou contradictoires entre sources.
+- Si les extraits fournis ne permettent pas de répondre avec certitude, dis-le clairement au lieu de deviner.
+- Termine ta réponse par une liste des sources utilisées : nom de fichier, langue, page.
+"""
+
+NO_CONTEXT_TEMPLATE = {
+    "en": "I could not find a sufficiently relevant passage in the knowledge base to answer this question reliably. Could you rephrase it, or would you like me to search across all languages?",
+    "fr": "Je n'ai pas trouvé d'extrait suffisamment pertinent dans la base de connaissances pour répondre de façon fiable à cette question. Pouvez-vous la reformuler, ou souhaitez-vous que j'élargisse la recherche à toutes les langues ?",
+    "ru": "Мне не удалось найти в базе знаний достаточно релевантный фрагмент, чтобы дать надёжный ответ на этот вопрос. Не могли бы вы переформулировать вопрос, или хотите, чтобы я расширил поиск на все языки?",
+    "es": "No he encontrado un pasaje suficientemente relevante en la base de conocimientos para responder con fiabilidad a esta pregunta. ¿Podría reformularla, o desea que amplíe la búsqueda a todos los idiomas?",
+    "ar": "لم أتمكن من العثور على مقطع ذي صلة كافية في قاعدة المعرفة للإجابة على هذا السؤال بشكل موثوق. هل يمكنك إعادة صياغته، أم ترغب في أن أوسّع البحث ليشمل جميع اللغات؟",
+    "pt": "Não encontrei um trecho suficientemente relevante na base de conhecimento para responder com fiabilidade a esta pergunta. Pode reformulá-la, ou prefere que eu alargue a pesquisa a todos os idiomas?",
+}
+
+
+def format_context(hits: list[SearchHit]) -> str:
+    blocks = []
+    for i, hit in enumerate(hits, start=1):
+        blocks.append(
+            f"[Source {i}]\n"
+            f"Langue : {hit.language}\n"
+            f"Fichier : {hit.source_file}\n"
+            f"Page : {hit.page}\n"
+            f"Texte : « {hit.text.strip()} »"
+        )
+    return "\n\n".join(blocks)
+
+
+def build_messages(
+    question: str,
+    hits: list[SearchHit],
+    target_language: str,
+) -> list[dict]:
+    system_prompt = SYSTEM_PROMPT_TEMPLATE.format(
+        target_language=language_label(target_language)
+    )
+    context = format_context(hits)
+    user_content = f"Question :\n{question}\n\nExtraits :\n{context}"
+    return [
+        {"role": "system", "content": system_prompt},
+        {"role": "user", "content": user_content},
+    ]
+
+
+def no_context_message(target_language: str) -> str:
+    return NO_CONTEXT_TEMPLATE.get(target_language, NO_CONTEXT_TEMPLATE["en"])

core/ingestion/chunker.py

@@ -0,0 +1,77 @@
+"""
+Découpage du texte en chunks adaptés à la langue.
+
+Principe : on découpe par phrases/paragraphes (pas par nombre brut de
+caractères) pour ne jamais couper une idée en deux, avec un recouvrement
+("overlap") afin de ne pas perdre le contexte à la frontière entre deux
+chunks. Le découpage par mots (et non uniquement par espaces) fonctionne
+correctement pour l'arabe et le russe car on s'appuie sur les limites de
+phrases Unicode plutôt que sur des heuristiques latines.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+_SENTENCE_SPLIT_RE = re.compile(
+    r"(?<=[\.\!\?؟۔。])\s+|\n{2,}"
+)
+
+
+@dataclass
+class Chunk:
+    text: str
+    index: int
+
+
+def _approx_token_count(text: str) -> int:
+    # Approximation simple et rapide, indépendante de la langue :
+    # ~1 token ≈ 0.75 mot pour les langues à espaces, on reste conservateur.
+    return max(1, len(text.split()))
+
+
+def split_into_sentences(text: str) -> list[str]:
+    text = text.strip()
+    if not text:
+        return []
+    sentences = [s.strip() for s in _SENTENCE_SPLIT_RE.split(text) if s.strip()]
+    return sentences or [text]
+
+
+def chunk_text(
+    text: str,
+    chunk_size_tokens: int = 350,
+    overlap_tokens: int = 60,
+) -> list[Chunk]:
+    """Découpe `text` en chunks de ~chunk_size_tokens avec recouvrement."""
+    sentences = split_into_sentences(text)
+    chunks: list[Chunk] = []
+    current: list[str] = []
+    current_tokens = 0
+
+    def flush():
+        if current:
+            chunks.append(Chunk(text=" ".join(current).strip(), index=len(chunks)))
+
+    for sentence in sentences:
+        sentence_tokens = _approx_token_count(sentence)
+
+        if current_tokens + sentence_tokens > chunk_size_tokens and current:
+            flush()
+            # Recouvrement : on reprend la fin du chunk précédent.
+            overlap_sentences: list[str] = []
+            overlap_count = 0
+            for s in reversed(current):
+                t = _approx_token_count(s)
+                if overlap_count + t > overlap_tokens:
+                    break
+                overlap_sentences.insert(0, s)
+                overlap_count += t
+            current = overlap_sentences
+            current_tokens = overlap_count
+
+        current.append(sentence)
+        current_tokens += sentence_tokens
+
+    flush()
+    return chunks or [Chunk(text=text.strip(), index=0)]

core/ingestion/indexer.py

@@ -0,0 +1,198 @@
+"""
+Pipeline d'ingestion complet : dossier `knowledge_base/<lang>/*` -> chunks
+avec métadonnées -> embeddings -> fichier Parquet -> dataset privé Hugging
+Face.
+
+Principe clé du projet (voir README) : on N'écrase JAMAIS la langue
+d'origine. Chaque chunk conserve son texte natif, sa langue détectée/
+déclarée, son fichier et sa page — la traduction n'intervient que plus
+tard, côté génération, jamais côté indexation.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+import pandas as pd
+
+from core.ingestion.chunker import chunk_text
+from core.ingestion.language_detector import detect_language
+from core.ingestion.loaders import load_file
+from config import settings
+
+
+@dataclass
+class ChunkRecord:
+    chunk_id: str
+    document_id: str
+    source_file: str
+    page: int
+    language: str
+    title: str | None
+    text_direction: str
+    text: str
+    embedding: list[float]
+
+
+def _document_id(source_file: str, declared_lang: str) -> str:
+    stem = Path(source_file).stem
+    return f"{declared_lang}_{stem}"
+
+
+def _chunk_id(document_id: str, page: int, chunk_index: int) -> str:
+    return f"{document_id}_p{page:03d}_c{chunk_index:02d}"
+
+
+def iter_knowledge_base(kb_dir: Path):
+    """
+    Parcourt `kb_dir/<lang_code>/*.{md,pdf,docx,html,csv}`.
+    Le sous-dossier donne la langue DÉCLARÉE du document (fiable, fournie
+    par l'entreprise) ; on la confronte à la langue détectée automatiquement
+    pour repérer les documents mal classés.
+    """
+    from config import SUPPORTED_LANGUAGES
+
+    for lang_dir in sorted(kb_dir.iterdir()):
+        if not lang_dir.is_dir() or lang_dir.name not in SUPPORTED_LANGUAGES:
+            continue
+        declared_lang = lang_dir.name
+        for file_path in sorted(lang_dir.rglob("*")):
+            if file_path.is_file() and file_path.suffix.lower() in {
+                ".md", ".markdown", ".html", ".htm", ".csv", ".pdf", ".docx",
+            }:
+                yield declared_lang, file_path
+
+
+def build_chunk_records(
+    kb_dir: Path,
+    embed_fn=None,
+    progress_cb=None,
+) -> list[ChunkRecord]:
+    """
+    embed_fn: fonction (list[str]) -> list[list[float]] injectable pour les
+    tests (évite tout appel réseau). Par défaut, utilise l'API HF réelle.
+    """
+    from config import SUPPORTED_LANGUAGES
+
+    if embed_fn is None:
+        from core.retrieval.embeddings import embed_texts
+
+        def embed_fn(texts):
+            return embed_texts(texts, kind="passage").tolist()
+
+    all_chunks: list[tuple[ChunkRecord, None]] = []
+    pending_texts: list[str] = []
+    pending_meta: list[dict] = []
+
+    for declared_lang, file_path in iter_knowledge_base(kb_dir):
+        pages = load_file(file_path)
+        document_id = _document_id(file_path.name, declared_lang)
+        text_direction = SUPPORTED_LANGUAGES[declared_lang]["dir"]
+
+        for page in pages:
+            detected_lang, confidence = detect_language(page.text)
+            # La langue déclarée (dossier) fait foi ; on journalise un écart
+            # éventuel pour audit qualité plutôt que de rejeter le document.
+            final_lang = declared_lang
+
+            for chunk in chunk_text(
+                page.text,
+                chunk_size_tokens=settings.chunk_size_tokens,
+                overlap_tokens=settings.chunk_overlap_tokens,
+            ):
+                if not chunk.text.strip():
+                    continue
+                chunk_id = _chunk_id(document_id, page.page, chunk.index)
+                pending_texts.append(chunk.text)
+                pending_meta.append(
+                    dict(
+                        chunk_id=chunk_id,
+                        document_id=document_id,
+                        source_file=file_path.name,
+                        page=page.page,
+                        language=final_lang,
+                        title=page.title,
+                        text_direction=text_direction,
+                        text=chunk.text,
+                        detected_language=detected_lang,
+                        detection_confidence=round(confidence, 3),
+                    )
+                )
+
+        if progress_cb:
+            progress_cb(file_path.name, declared_lang)
+
+    # Embeddings par lot (plus rapide, moins d'appels réseau).
+    records: list[ChunkRecord] = []
+    batch_size = 32
+    for i in range(0, len(pending_texts), batch_size):
+        batch_texts = pending_texts[i : i + batch_size]
+        batch_meta = pending_meta[i : i + batch_size]
+        vectors = embed_fn(batch_texts)
+        for meta, vector in zip(batch_meta, vectors):
+            meta_copy = dict(meta)
+            detected_language = meta_copy.pop("detected_language")
+            detection_confidence = meta_copy.pop("detection_confidence")
+            records.append(
+                ChunkRecord(embedding=list(vector), **meta_copy)
+            )
+            # écart de langue -> log simple sur stdout (visible en ingestion)
+            if detected_language not in ("unknown", meta_copy["language"]):
+                print(
+                    f"[audit langue] {meta_copy['chunk_id']}: dossier="
+                    f"{meta_copy['language']} vs détecté={detected_language} "
+                    f"(confiance={detection_confidence})"
+                )
+
+    return records
+
+
+def records_to_dataframe(records: list[ChunkRecord]) -> pd.DataFrame:
+    return pd.DataFrame([asdict(r) for r in records])
+
+
+def save_index_locally(records: list[ChunkRecord], out_dir: Path) -> Path:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    df = records_to_dataframe(records)
+    parquet_path = out_dir / "chunks.parquet"
+    df.to_parquet(parquet_path, index=False)
+
+    stats = {
+        "total_chunks": len(records),
+        "by_language": df["language"].value_counts().to_dict() if len(df) else {},
+        "embedding_model": settings.embedding_model,
+        "embedding_dim": settings.embedding_dim,
+    }
+    (out_dir / "manifest.json").write_text(
+        json.dumps(stats, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    return parquet_path
+
+
+def push_index_to_hub(local_dir: Path, repo_id: str, token: str) -> str:
+    """Pousse chunks.parquet + manifest.json vers un dataset privé HF."""
+    from huggingface_hub import HfApi
+
+    api = HfApi(token=token)
+    api.create_repo(
+        repo_id=repo_id, repo_type="dataset", private=True, exist_ok=True
+    )
+    api.upload_folder(
+        folder_path=str(local_dir),
+        repo_id=repo_id,
+        repo_type="dataset",
+        allow_patterns=["*.parquet", "*.json"],
+        commit_message="Mise à jour de l'index PolyglotRAG",
+    )
+    return f"https://huggingface.co/datasets/{repo_id}"
+
+
+def fingerprint_kb(kb_dir: Path) -> str:
+    """Empreinte simple du corpus (pour savoir si une ré-ingestion est utile)."""
+    h = hashlib.sha256()
+    for _, file_path in iter_knowledge_base(kb_dir):
+        h.update(file_path.name.encode())
+        h.update(str(file_path.stat().st_mtime_ns).encode())
+    return h.hexdigest()[:16]

core/ingestion/language_detector.py

@@ -0,0 +1,58 @@
+"""
+Détection de la langue d'un texte (document ou question utilisateur).
+
+Utilise `lingua-language-detector`, qui fonctionne hors-ligne (aucun appel
+API), gère bien les 6 langues du projet et fournit un score de confiance —
+utile pour laisser l'utilisateur corriger la langue détectée en cas de
+texte très court ou ambigu (ex : « OK », un simple identifiant, etc.).
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+from config import SUPPORTED_LANGUAGES
+
+_LANGUAGE_NAME_TO_ISO = {
+    "ENGLISH": "en",
+    "FRENCH": "fr",
+    "RUSSIAN": "ru",
+    "SPANISH": "es",
+    "ARABIC": "ar",
+    "PORTUGUESE": "pt",
+}
+
+
+@lru_cache(maxsize=1)
+def _get_detector():
+    from lingua import Language, LanguageDetectorBuilder
+
+    langs = [getattr(Language, name) for name in _LANGUAGE_NAME_TO_ISO]
+    return LanguageDetectorBuilder.from_languages(*langs).build()
+
+
+def detect_language(text: str, min_confidence: float = 0.20) -> tuple[str, float]:
+    """
+    Retourne (code_iso, confiance). code_iso == "unknown" si la confiance
+    est trop faible ou si le texte est vide/trop court pour être fiable.
+    """
+    clean = (text or "").strip()
+    if len(clean) < 2:
+        return "unknown", 0.0
+
+    detector = _get_detector()
+    confidence_values = detector.compute_language_confidence_values(clean)
+    if not confidence_values:
+        return "unknown", 0.0
+
+    best = confidence_values[0]
+    iso = _LANGUAGE_NAME_TO_ISO.get(best.language.name, "unknown")
+
+    if best.value < min_confidence or iso not in SUPPORTED_LANGUAGES:
+        return "unknown", float(best.value)
+
+    return iso, float(best.value)
+
+
+def language_label(iso_code: str) -> str:
+    info = SUPPORTED_LANGUAGES.get(iso_code)
+    return info["name"] if info else iso_code

core/ingestion/loaders.py

@@ -0,0 +1,119 @@
+"""
+Extraction de texte à partir de fichiers PDF, DOCX, Markdown, HTML et CSV.
+
+Chaque loader retourne une liste de `RawPage` : une unité (page ou ligne)
+avec son texte brut et le numéro de page quand la notion existe, afin de
+pouvoir citer précisément la source (fichier + page) plus tard.
+"""
+from __future__ import annotations
+
+import csv
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class RawPage:
+    text: str
+    page: int
+    title: str | None = None
+
+
+def load_markdown(path: Path) -> list[RawPage]:
+    text = path.read_text(encoding="utf-8")
+    title = None
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("# "):
+            title = stripped.lstrip("#").strip()
+            break
+    return [RawPage(text=text, page=1, title=title)]
+
+
+def load_html(path: Path) -> list[RawPage]:
+    from bs4 import BeautifulSoup
+
+    html = path.read_text(encoding="utf-8", errors="ignore")
+    soup = BeautifulSoup(html, "html.parser")
+    title_tag = soup.find("title") or soup.find("h1")
+    title = title_tag.get_text(strip=True) if title_tag else None
+    text = soup.get_text(separator="\n")
+    return [RawPage(text=text, page=1, title=title)]
+
+
+def load_csv(path: Path) -> list[RawPage]:
+    rows_text = []
+    with path.open(encoding="utf-8", errors="ignore", newline="") as fh:
+        reader = csv.reader(fh)
+        header = next(reader, None)
+        for i, row in enumerate(reader, start=1):
+            if header:
+                row_text = "; ".join(
+                    f"{h.strip()}: {v.strip()}" for h, v in zip(header, row)
+                )
+            else:
+                row_text = ", ".join(row)
+            rows_text.append(row_text)
+    # On regroupe les lignes par blocs de 40 pour éviter des chunks minuscules.
+    pages = []
+    block = 40
+    for i in range(0, len(rows_text), block):
+        chunk = "\n".join(rows_text[i : i + block])
+        pages.append(RawPage(text=chunk, page=(i // block) + 1, title=path.stem))
+    return pages or [RawPage(text="", page=1, title=path.stem)]
+
+
+def load_pdf(path: Path) -> list[RawPage]:
+    from pypdf import PdfReader
+
+    reader = PdfReader(str(path))
+    pages = []
+    title = None
+    meta_title = getattr(reader, "metadata", None)
+    if meta_title and getattr(meta_title, "title", None):
+        title = meta_title.title
+    for i, page in enumerate(reader.pages, start=1):
+        text = page.extract_text() or ""
+        if not text.strip():
+            # Page probablement scannée sans OCR préalable : on le signale
+            # plutôt que d'indexer une page vide silencieusement.
+            text = "[PAGE SANS TEXTE EXTRACTIBLE — OCR REQUIS]"
+        pages.append(RawPage(text=text, page=i, title=title))
+    return pages
+
+
+def load_docx(path: Path) -> list[RawPage]:
+    import docx
+
+    document = docx.Document(str(path))
+    title = None
+    paragraphs = []
+    for para in document.paragraphs:
+        if not title and para.style and para.style.name.lower().startswith("heading"):
+            title = para.text.strip()
+        if para.text.strip():
+            paragraphs.append(para.text)
+    text = "\n".join(paragraphs)
+    return [RawPage(text=text, page=1, title=title or path.stem)]
+
+
+LOADERS = {
+    ".md": load_markdown,
+    ".markdown": load_markdown,
+    ".html": load_html,
+    ".htm": load_html,
+    ".csv": load_csv,
+    ".pdf": load_pdf,
+    ".docx": load_docx,
+}
+
+
+def load_file(path: Path) -> list[RawPage]:
+    """Route un fichier vers le loader adapté à son extension."""
+    loader = LOADERS.get(path.suffix.lower())
+    if loader is None:
+        raise ValueError(
+            f"Format non supporté pour '{path.name}' "
+            f"(extensions supportées : {', '.join(LOADERS)})"
+        )
+    return loader(path)

core/metrics/logger.py

@@ -0,0 +1,172 @@
+"""
+Journalisation des requêtes RAG dans une base SQLite locale, pour
+alimenter la page Admin (page:metrics) : volume par langue, latence,
+score de confiance moyen, taux d'abstention, paires de langues
+cross-lingues (langue question -> langue des sources utilisées), etc.
+
+SQLite est suffisant pour un tableau de bord mono-instance ; la base
+peut être snapshotée périodiquement vers le dataset HF privé si l'on
+veut la persister au-delà du cycle de vie du Space (voir
+`snapshot_to_hub`).
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from contextlib import contextmanager
+from pathlib import Path
+
+from config import settings
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS queries (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    timestamp REAL NOT NULL,
+    question TEXT NOT NULL,
+    query_language TEXT,
+    target_language TEXT,
+    confidence_score REAL,
+    is_sufficient INTEGER,
+    used_fallback INTEGER,
+    retrieval_latency_ms REAL,
+    generation_latency_ms REAL,
+    total_latency_ms REAL,
+    sources_json TEXT,
+    source_languages_json TEXT
+);
+"""
+
+
+def _db_path() -> Path:
+    path = Path(settings.metrics_db_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+@contextmanager
+def _connect():
+    conn = sqlite3.connect(_db_path())
+    try:
+        conn.execute(_SCHEMA)
+        yield conn
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def log_query(
+    question: str,
+    query_language: str,
+    target_language: str,
+    confidence_score: float,
+    is_sufficient: bool,
+    used_fallback: bool,
+    retrieval_latency_ms: float,
+    generation_latency_ms: float,
+    sources: list[dict],
+) -> None:
+    source_languages = sorted({s["language"] for s in sources}) if sources else []
+    with _connect() as conn:
+        conn.execute(
+            """
+            INSERT INTO queries (
+                timestamp, question, query_language, target_language,
+                confidence_score, is_sufficient, used_fallback,
+                retrieval_latency_ms, generation_latency_ms, total_latency_ms,
+                sources_json, source_languages_json
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                time.time(),
+                question[:2000],
+                query_language,
+                target_language,
+                confidence_score,
+                int(is_sufficient),
+                int(used_fallback),
+                retrieval_latency_ms,
+                generation_latency_ms,
+                retrieval_latency_ms + generation_latency_ms,
+                json.dumps(sources, ensure_ascii=False),
+                json.dumps(source_languages, ensure_ascii=False),
+            ),
+        )
+
+
+def fetch_recent(limit: int = 200) -> list[dict]:
+    with _connect() as conn:
+        conn.row_factory = sqlite3.Row
+        rows = conn.execute(
+            "SELECT * FROM queries ORDER BY timestamp DESC LIMIT ?", (limit,)
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+
+def summary_metrics() -> dict:
+    """Agrège les métriques utilisées par l'onglet Admin."""
+    with _connect() as conn:
+        conn.row_factory = sqlite3.Row
+        total = conn.execute("SELECT COUNT(*) AS n FROM queries").fetchone()["n"]
+        if total == 0:
+            return {
+                "total_queries": 0,
+                "abstention_rate": 0.0,
+                "avg_confidence": 0.0,
+                "avg_latency_ms": 0.0,
+                "by_query_language": {},
+                "by_target_language": {},
+                "cross_lingual_rate": 0.0,
+            }
+
+        abstentions = conn.execute(
+            "SELECT COUNT(*) AS n FROM queries WHERE used_fallback = 1"
+        ).fetchone()["n"]
+        avg_conf = conn.execute(
+            "SELECT AVG(confidence_score) AS v FROM queries"
+        ).fetchone()["v"]
+        avg_latency = conn.execute(
+            "SELECT AVG(total_latency_ms) AS v FROM queries"
+        ).fetchone()["v"]
+
+        by_query_lang = {
+            row["query_language"]: row["n"]
+            for row in conn.execute(
+                "SELECT query_language, COUNT(*) AS n FROM queries "
+                "GROUP BY query_language"
+            ).fetchall()
+        }
+        by_target_lang = {
+            row["target_language"]: row["n"]
+            for row in conn.execute(
+                "SELECT target_language, COUNT(*) AS n FROM queries "
+                "GROUP BY target_language"
+            ).fetchall()
+        }
+
+        # Taux de requêtes cross-lingues : langue question absente des
+        # langues sources utilisées (preuve que la recherche cross-lingue
+        # a effectivement servi, et pas seulement une recherche mono-langue).
+        rows = conn.execute(
+            "SELECT query_language, source_languages_json FROM queries "
+            "WHERE used_fallback = 0"
+        ).fetchall()
+        cross_count = 0
+        counted = 0
+        for row in rows:
+            src_langs = json.loads(row["source_languages_json"] or "[]")
+            if not src_langs:
+                continue
+            counted += 1
+            if row["query_language"] not in src_langs:
+                cross_count += 1
+
+        return {
+            "total_queries": total,
+            "abstention_rate": round(abstentions / total, 3),
+            "avg_confidence": round(avg_conf or 0.0, 3),
+            "avg_latency_ms": round(avg_latency or 0.0, 1),
+            "by_query_language": by_query_lang,
+            "by_target_language": by_target_lang,
+            "cross_lingual_rate": round(cross_count / counted, 3) if counted else 0.0,
+        }

core/optimization/cache.py

@@ -0,0 +1,70 @@
+"""
+Cache générique (TTL + taille bornée) partagé par tout le pipeline.
+
+Deux usages concrets dans PolyglotRAG :
+  1. `embedding_cache` : évite de rappeler l'API d'embeddings pour une même
+     question déjà posée récemment (économie d'appels réseau + latence).
+  2. `answer_cache` (utilisé par `core.pipeline`) : évite de refaire tout le
+     cycle retrieval + génération LLM pour une question strictement
+     identique posée à nouveau pendant la fenêtre de TTL.
+
+Activable/désactivable via `ENABLE_CACHE` (config.py) ; désactivé, chaque
+`get()` renvoie toujours None et `set()` ne fait rien, sans branche
+conditionnelle à ajouter dans le code appelant.
+"""
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+from cachetools import TTLCache
+
+from config import settings
+
+
+class SimpleCache:
+    def __init__(self, maxsize: int, ttl: int, enabled: bool = True) -> None:
+        self._enabled = enabled
+        self._lock = threading.Lock()
+        self._store: TTLCache | None = TTLCache(maxsize=maxsize, ttl=ttl) if enabled else None
+
+    def get(self, key: str) -> Any | None:
+        if not self._enabled:
+            return None
+        with self._lock:
+            return self._store.get(key)
+
+    def set(self, key: str, value: Any) -> None:
+        if not self._enabled:
+            return
+        with self._lock:
+            self._store[key] = value
+
+    def clear(self) -> None:
+        if self._enabled:
+            with self._lock:
+                self._store.clear()
+
+    def stats(self) -> dict:
+        if not self._enabled:
+            return {"enabled": False, "size": 0, "maxsize": 0}
+        with self._lock:
+            return {
+                "enabled": True,
+                "size": len(self._store),
+                "maxsize": self._store.maxsize,
+            }
+
+
+def make_cache_key(*parts: str) -> str:
+    return "||".join(parts)
+
+
+# Deux caches distincts (tailles/TTL identiques par défaut, mais séparés
+# pour ne pas mélanger des vecteurs d'embeddings et des réponses complètes).
+embedding_cache = SimpleCache(
+    maxsize=settings.cache_max_size, ttl=settings.cache_ttl_seconds, enabled=settings.enable_cache
+)
+answer_cache = SimpleCache(
+    maxsize=settings.cache_max_size, ttl=settings.cache_ttl_seconds, enabled=settings.enable_cache
+)

core/pipeline.py

@@ -0,0 +1,106 @@
+"""
+Orchestration bout-en-bout d'une question utilisateur.
+
+Centralise les optimisations du projet, pour qu'elles ne soient pas
+éparpillées dans la couche UI :
+
+  1. **Cache réponse** : une question strictement identique (même langue de
+     réponse, même filtre de langue) posée pendant la fenêtre de TTL renvoie
+     instantanément le résultat déjà calculé, sans repasser ni par la
+     recherche vectorielle ni par le LLM.
+  2. **Cache embedding** (voir `core.retrieval.embeddings.embed_query`) :
+     complémentaire, utile dès que la formulation de la question change
+     mais que le cache réponse ne peut pas s'appliquer.
+  3. **Recherche approximative (ANN)** : déléguée à `VectorStore`
+     (FAISS HNSW par défaut, voir `core.retrieval.vector_store`).
+  4. **Top-k final réduit** : `settings.top_k_final` (2 par défaut) limite
+     le nombre de passages effectivement envoyés au LLM.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+from core.generation.answer_generator import GenerationResult, generate_answer
+from core.metrics.logger import log_query
+from core.optimization.cache import answer_cache, make_cache_key
+from core.retrieval.hybrid_search import RetrievalResult, retrieve
+from core.retrieval.vector_store import VectorStore
+
+
+@dataclass
+class PipelineResult:
+    generation: GenerationResult
+    retrieval: RetrievalResult
+    target_language: str
+    retrieval_latency_ms: float
+    from_cache: bool
+
+
+def ask(
+    question: str,
+    store: VectorStore,
+    response_language_choice: str,
+    language_filter: str | None,
+) -> PipelineResult:
+    cache_key = make_cache_key(
+        question.strip().lower(), response_language_choice, language_filter or "all"
+    )
+    cached = answer_cache.get(cache_key)
+    if cached is not None:
+        retrieval, generation, target_language, retrieval_latency_ms = cached
+        # On journalise même les réponses servies depuis le cache : le
+        # tableau de bord Admin doit refléter le volume RÉEL de questions
+        # posées, pas seulement les questions qui ont déclenché un appel LLM.
+        log_query(
+            question=question,
+            query_language=retrieval.query_language,
+            target_language=target_language,
+            confidence_score=retrieval.confidence_score,
+            is_sufficient=retrieval.is_sufficient,
+            used_fallback=generation.used_fallback,
+            retrieval_latency_ms=0.0,
+            generation_latency_ms=0.0,
+            sources=generation.sources,
+        )
+        return PipelineResult(
+            generation=generation,
+            retrieval=retrieval,
+            target_language=target_language,
+            retrieval_latency_ms=retrieval_latency_ms,
+            from_cache=True,
+        )
+
+    t0 = time.perf_counter()
+    retrieval = retrieve(question, store, language_filter=language_filter)
+    retrieval_latency_ms = (time.perf_counter() - t0) * 1000
+
+    target_language = (
+        retrieval.query_language if response_language_choice == "auto" else response_language_choice
+    )
+    if target_language == "unknown":
+        target_language = "en"
+
+    generation = generate_answer(question, retrieval, target_language)
+
+    log_query(
+        question=question,
+        query_language=retrieval.query_language,
+        target_language=target_language,
+        confidence_score=retrieval.confidence_score,
+        is_sufficient=retrieval.is_sufficient,
+        used_fallback=generation.used_fallback,
+        retrieval_latency_ms=retrieval_latency_ms,
+        generation_latency_ms=generation.latency_seconds * 1000,
+        sources=generation.sources,
+    )
+
+    answer_cache.set(cache_key, (retrieval, generation, target_language, retrieval_latency_ms))
+
+    return PipelineResult(
+        generation=generation,
+        retrieval=retrieval,
+        target_language=target_language,
+        retrieval_latency_ms=retrieval_latency_ms,
+        from_cache=False,
+    )

core/retrieval/embeddings.py

@@ -0,0 +1,94 @@
+"""
+Génération d'embeddings multilingues via l'API "Inference Providers" de
+Hugging Face (provider `hf-inference`) — un seul jeton (HF_TOKEN) suffit,
+aucun compte tiers requis.
+
+Modèle par défaut : BAAI/bge-m3 (>100 langues, recherche cross-lingue native
+dans un espace sémantique partagé). Alternative légère configurable :
+intfloat/multilingual-e5-base (nécessite les préfixes "query:"/"passage:").
+"""
+from __future__ import annotations
+
+import time
+from functools import lru_cache
+
+import numpy as np
+
+from config import settings
+from core.optimization.cache import embedding_cache, make_cache_key
+
+
+@lru_cache(maxsize=1)
+def _get_client():
+    from huggingface_hub import InferenceClient
+
+    if not settings.hf_token:
+        raise RuntimeError(
+            "HF_TOKEN manquant : impossible d'appeler l'API d'embeddings."
+        )
+    return InferenceClient(provider="hf-inference", api_key=settings.hf_token)
+
+
+def _prefix(texts: list[str], kind: str) -> list[str]:
+    if not settings.use_query_passage_prefix:
+        return texts
+    tag = "query:" if kind == "query" else "passage:"
+    return [f"{tag} {t}" for t in texts]
+
+
+def _normalize(vectors: np.ndarray) -> np.ndarray:
+    norms = np.linalg.norm(vectors, axis=-1, keepdims=True)
+    norms[norms == 0] = 1.0
+    return vectors / norms
+
+
+def embed_texts(
+    texts: list[str],
+    kind: str = "passage",
+    max_retries: int = 3,
+) -> np.ndarray:
+    """
+    Encode une liste de textes en vecteurs normalisés (similarité cosinus).
+    `kind` ∈ {"passage", "query"} détermine le préfixe éventuel.
+    """
+    if not texts:
+        return np.zeros((0, settings.embedding_dim), dtype="float32")
+
+    client = _get_client()
+    prefixed = _prefix(texts, kind)
+
+    last_error: Exception | None = None
+    for attempt in range(max_retries):
+        try:
+            result = client.feature_extraction(
+                prefixed, model=settings.embedding_model
+            )
+            vectors = np.array(result, dtype="float32")
+            # Certains providers renvoient (n, seq_len, dim) -> mean pooling.
+            if vectors.ndim == 3:
+                vectors = vectors.mean(axis=1)
+            return _normalize(vectors)
+        except Exception as exc:  # noqa: BLE001 - on veut logguer puis retenter
+            last_error = exc
+            time.sleep(1.5 * (attempt + 1))
+
+    raise RuntimeError(
+        f"Échec de l'appel d'embeddings après {max_retries} tentatives : {last_error}"
+    ) from last_error
+
+
+def embed_query(text: str) -> np.ndarray:
+    """
+    Comme `embed_texts`, mais met en cache le vecteur d'une question déjà
+    posée récemment (même modèle d'embeddings) : une question répétée par
+    plusieurs utilisateurs, ou reformulée à l'identique, ne déclenche plus
+    d'appel réseau tant que l'entrée est encore dans le cache (TTL configurable).
+    """
+    key = make_cache_key("query_embedding", settings.embedding_model, text.strip().lower())
+    cached = embedding_cache.get(key)
+    if cached is not None:
+        return cached
+
+    vector = embed_texts([text], kind="query")[0]
+    embedding_cache.set(key, vector)
+    return vector

core/retrieval/hybrid_search.py

@@ -0,0 +1,68 @@
+"""
+Recherche cross-lingue en 3 modes (voir README / onglet Architecture) :
+
+1. Cross-lingue global   -> cherche dans toutes les langues.
+2. Filtré par langue     -> restreint aux documents d'une langue choisie.
+3. Priorité locale       -> léger bonus de score pour la langue de la
+                            question, sans jamais exclure les autres langues.
+
+Étapes : top-15 brut -> bonus langue -> tri -> top-5 final -> score de
+confiance global. Si le score de confiance est trop faible, on répond que
+le corpus ne contient probablement pas l'information (mode strict / Corrective
+RAG minimal), plutôt que d'halluciner.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from core.ingestion.language_detector import detect_language
+from core.retrieval.embeddings import embed_query
+from core.retrieval.vector_store import SearchHit, VectorStore
+from config import settings
+
+
+@dataclass
+class RetrievalResult:
+    hits: list[SearchHit]
+    query_language: str
+    query_language_confidence: float
+    confidence_score: float
+    is_sufficient: bool
+
+
+def retrieve(
+    question: str,
+    store: VectorStore,
+    language_filter: str | None = None,
+    forced_query_language: str | None = None,
+) -> RetrievalResult:
+    query_lang, lang_conf = (
+        (forced_query_language, 1.0)
+        if forced_query_language
+        else detect_language(question)
+    )
+
+    query_vector = embed_query(question)
+    raw_hits = store.search(query_vector, top_k=settings.top_k_retrieve)
+
+    if language_filter:
+        raw_hits = [h for h in raw_hits if h.language == language_filter]
+
+    # Bonus léger pour la langue de la question (priorité locale puis globale).
+    def adjusted_score(hit: SearchHit) -> float:
+        bonus = settings.same_language_bonus if hit.language == query_lang else 0.0
+        return hit.score + bonus
+
+    ranked = sorted(raw_hits, key=adjusted_score, reverse=True)
+    top_hits = ranked[: settings.top_k_final]
+
+    confidence = top_hits[0].score if top_hits else 0.0
+    is_sufficient = confidence >= settings.min_confidence_score and bool(top_hits)
+
+    return RetrievalResult(
+        hits=top_hits,
+        query_language=query_lang,
+        query_language_confidence=lang_conf,
+        confidence_score=confidence,
+        is_sufficient=is_sufficient,
+    )

core/retrieval/vector_store.py

@@ -0,0 +1,184 @@
+"""
+Index vectoriel en mémoire (FAISS) construit à partir du Parquet stocké
+dans le dataset privé Hugging Face.
+
+Choix d'architecture assumé (documenté dans le README) : plutôt qu'un
+service Qdrant externe séparé — qui demanderait une seconde clé d'API et
+un second service à héberger — le vecteur-store tient dans le Space
+Gradio lui-même : au démarrage, on télécharge le Parquet privé (avec
+HF_TOKEN), on construit un index FAISS en mémoire. Pour un corpus de
+quelques dizaines de milliers de chunks (cas normal d'un MVP ou d'une
+PME), c'est largement suffisant et ça supprime une dépendance opérationnelle
+tout en respectant la contrainte « je n'ai qu'un jeton API Hugging Face ».
+"""
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from config import settings
+
+
+@dataclass
+class SearchHit:
+    chunk_id: str
+    document_id: str
+    source_file: str
+    page: int
+    language: str
+    title: str | None
+    text_direction: str
+    text: str
+    score: float
+
+
+class VectorStore:
+    """Encapsule le DataFrame de métadonnées + l'index FAISS associé."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self.df: pd.DataFrame | None = None
+        self.index = None  # faiss.Index
+        self.loaded_from: str | None = None
+        self.ann_index_type: str = settings.ann_index_type
+
+    # ------------------------------------------------------------------ #
+    # Chargement
+    # ------------------------------------------------------------------ #
+    def load_from_parquet(self, parquet_path: Path) -> None:
+        df = pd.read_parquet(parquet_path)
+        self._build_index(df)
+        self.loaded_from = str(parquet_path)
+
+    def load_from_hub(self, repo_id: str, token: str, local_cache: Path) -> None:
+        from huggingface_hub import hf_hub_download
+
+        local_cache.mkdir(parents=True, exist_ok=True)
+        parquet_file = hf_hub_download(
+            repo_id=repo_id,
+            repo_type="dataset",
+            filename="chunks.parquet",
+            token=token,
+            local_dir=str(local_cache),
+        )
+        self.load_from_parquet(Path(parquet_file))
+        self.loaded_from = f"hf://datasets/{repo_id}"
+
+    def _build_index(self, df: pd.DataFrame) -> None:
+        import faiss
+
+        with self._lock:
+            self.df = df.reset_index(drop=True)
+            if len(self.df) == 0:
+                self.index = None
+                return
+            vectors = np.vstack(
+                self.df["embedding"].apply(lambda v: np.array(v, dtype="float32"))
+            )
+            dim = vectors.shape[1]
+
+            if settings.ann_index_type == "hnsw":
+                # Recherche APPROXIMATIVE (ANN) : FAISS HNSW. Pas d'étape
+                # d'entraînement requise (contrairement à IVF), donc valable
+                # même sur un tout petit corpus de démo. `efSearch` contrôle
+                # le compromis vitesse/rappel au moment de la requête.
+                index = faiss.IndexHNSWFlat(dim, settings.ann_hnsw_m, faiss.METRIC_INNER_PRODUCT)
+                index.hnsw.efConstruction = max(40, settings.ann_hnsw_m * 2)
+                index.add(vectors)
+                index.hnsw.efSearch = settings.ann_ef_search
+            else:
+                # Recherche EXACTE (produit scalaire = cosinus, vecteurs
+                # normalisés) : plus lente sur un grand corpus, utile en
+                # comparaison/qualité ou sur un petit corpus.
+                index = faiss.IndexFlatIP(dim)
+                index.add(vectors)
+
+            self.index = index
+            self.ann_index_type = settings.ann_index_type
+
+    # ------------------------------------------------------------------ #
+    # Recherche
+    # ------------------------------------------------------------------ #
+    def is_ready(self) -> bool:
+        return self.index is not None and self.df is not None and len(self.df) > 0
+
+    def search(self, query_vector: np.ndarray, top_k: int = 15) -> list[SearchHit]:
+        if not self.is_ready():
+            return []
+        query_vector = query_vector.reshape(1, -1).astype("float32")
+        scores, indices = self.index.search(query_vector, min(top_k, len(self.df)))
+        hits: list[SearchHit] = []
+        for score, idx in zip(scores[0], indices[0]):
+            if idx < 0:
+                continue
+            row = self.df.iloc[idx]
+            hits.append(
+                SearchHit(
+                    chunk_id=row["chunk_id"],
+                    document_id=row["document_id"],
+                    source_file=row["source_file"],
+                    page=int(row["page"]),
+                    language=row["language"],
+                    title=row.get("title"),
+                    text_direction=row.get("text_direction", "ltr"),
+                    text=row["text"],
+                    score=float(score),
+                )
+            )
+        return hits
+
+    def corpus_stats(self) -> dict:
+        if not self.is_ready():
+            return {"total_chunks": 0, "by_language": {}, "documents": 0, "ann_index_type": self.ann_index_type}
+        return {
+            "total_chunks": int(len(self.df)),
+            "by_language": self.df["language"].value_counts().to_dict(),
+            "documents": int(self.df["document_id"].nunique()),
+            "ann_index_type": self.ann_index_type,
+        }
+
+
+_store_singleton: VectorStore | None = None
+
+
+def get_vector_store() -> VectorStore:
+    """Charge (une seule fois) l'index, depuis le dataset HF si configuré,
+    sinon depuis le Parquet local (utile en développement)."""
+    global _store_singleton
+    if _store_singleton is not None:
+        return _store_singleton
+
+    store = VectorStore()
+    local_parquet = Path(settings.local_index_dir) / "chunks.parquet"
+
+    if settings.hf_dataset_repo and settings.hf_token:
+        try:
+            store.load_from_hub(
+                settings.hf_dataset_repo,
+                settings.hf_token,
+                Path(settings.local_index_dir) / "hub_cache",
+            )
+        except Exception as exc:  # noqa: BLE001
+            print(f"[vector_store] Impossible de charger le dataset HF ({exc}). "
+                  f"Repli sur l'index local si présent.")
+            if local_parquet.exists():
+                store.load_from_parquet(local_parquet)
+    elif local_parquet.exists():
+        store.load_from_parquet(local_parquet)
+    else:
+        print(
+            "[vector_store] Aucun index trouvé (ni dataset HF, ni Parquet local). "
+            "Lancez `python scripts/ingest.py` d'abord."
+        )
+
+    _store_singleton = store
+    return store
+
+
+def reset_vector_store_cache() -> None:
+    global _store_singleton
+    _store_singleton = None

core/ui/admin_tab.py

@@ -0,0 +1,136 @@
+"""Onglet Admin : métriques du RAG (volume, latence, langues, abstention)."""
+from __future__ import annotations
+
+import gradio as gr
+import pandas as pd
+
+from core.metrics.logger import fetch_recent, summary_metrics
+from core.optimization.cache import answer_cache, embedding_cache
+from core.retrieval.vector_store import get_vector_store
+from config import settings
+
+
+def _kpi_html(label: str, value: str) -> str:
+    return (
+        f'<div class="pg-kpi-card"><div class="pg-kpi-value">{value}</div>'
+        f'<div class="pg-kpi-label">{label}</div></div>'
+    )
+
+
+def _check_password(password: str) -> bool:
+    if not settings.admin_password:
+        return True  # aucun mot de passe configuré -> accès libre (démo)
+    return password == settings.admin_password
+
+
+def refresh_dashboard(password: str):
+    if not _check_password(password):
+        denied = "🔒 Mot de passe administrateur incorrect."
+        return (
+            gr.update(visible=False),
+            denied,
+            None,
+            None,
+            None,
+        )
+
+    metrics = summary_metrics()
+    store = get_vector_store()
+    corpus = store.corpus_stats()
+
+    answer_cache_stats = answer_cache.stats()
+    embedding_cache_stats = embedding_cache.stats()
+
+    kpis = "".join(
+        [
+            _kpi_html("Requêtes traitées", str(metrics["total_queries"])),
+            _kpi_html("Taux d'abstention", f"{metrics['abstention_rate']:.0%}"),
+            _kpi_html("Confiance moyenne", f"{metrics['avg_confidence']:.2f}"),
+            _kpi_html("Latence moyenne", f"{metrics['avg_latency_ms']:.0f} ms"),
+            _kpi_html("Chunks indexés", str(corpus["total_chunks"])),
+            _kpi_html("Documents indexés", str(corpus["documents"])),
+            _kpi_html("Index vectoriel", corpus.get("ann_index_type", "—").upper()),
+            _kpi_html(
+                "Cache réponses",
+                f"{answer_cache_stats['size']}/{answer_cache_stats['maxsize']}"
+                if answer_cache_stats["enabled"] else "désactivé",
+            ),
+            _kpi_html(
+                "Cache embeddings",
+                f"{embedding_cache_stats['size']}/{embedding_cache_stats['maxsize']}"
+                if embedding_cache_stats["enabled"] else "désactivé",
+            ),
+        ]
+    )
+    kpi_html = f'<div style="display:grid;grid-template-columns:repeat(3,1fr);gap:12px;">{kpis}</div>'
+
+    lang_query_df = pd.DataFrame(
+        {
+            "langue": list(metrics["by_query_language"].keys()) or ["—"],
+            "requêtes": list(metrics["by_query_language"].values()) or [0],
+        }
+    )
+    corpus_lang_df = pd.DataFrame(
+        {
+            "langue": list(corpus["by_language"].keys()) or ["—"],
+            "chunks": list(corpus["by_language"].values()) or [0],
+        }
+    )
+
+    recent = fetch_recent(limit=25)
+    recent_df = pd.DataFrame(
+        [
+            {
+                "question": r["question"][:90],
+                "langue question": r["query_language"],
+                "langue réponse": r["target_language"],
+                "confiance": round(r["confidence_score"], 2),
+                "abstention": bool(r["used_fallback"]),
+                "latence (ms)": round(r["total_latency_ms"], 0),
+            }
+            for r in recent
+        ]
+    )
+
+    return gr.update(visible=True), kpi_html, lang_query_df, corpus_lang_df, recent_df
+
+
+def build_admin_tab():
+    with gr.Column():
+        gr.Markdown(
+            "### 🔐 Tableau de bord administrateur — métriques RAG\n"
+            "Définissez `ADMIN_PASSWORD` (variable d'environnement) pour "
+            "protéger cet onglet en production."
+        )
+        with gr.Row():
+            password_box = gr.Textbox(
+                label="Mot de passe administrateur",
+                type="password",
+                scale=3,
+            )
+            refresh_btn = gr.Button("Actualiser le tableau de bord", variant="primary", scale=1)
+
+        dashboard_group = gr.Group(visible=False)
+        kpi_html_box = gr.HTML()
+
+        with dashboard_group:
+            with gr.Row():
+                with gr.Column():
+                    gr.Markdown("**Volume de requêtes par langue posée**")
+                    lang_query_plot = gr.BarPlot(
+                        x="langue", y="requêtes", title="", height=280
+                    )
+                with gr.Column():
+                    gr.Markdown("**Répartition du corpus indexé par langue**")
+                    corpus_lang_plot = gr.BarPlot(
+                        x="langue", y="chunks", title="", height=280
+                    )
+
+            gr.Markdown("**Historique des 25 dernières requêtes**")
+            recent_table = gr.Dataframe(wrap=True)
+
+        refresh_btn.click(
+            refresh_dashboard,
+            inputs=[password_box],
+            outputs=[dashboard_group, kpi_html_box, lang_query_plot, corpus_lang_plot, recent_table],
+        )

core/ui/architecture_tab.py

@@ -0,0 +1,42 @@
+"""Onglet Architecture : schéma du pipeline + explications synthétiques."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import gradio as gr
+
+_SVG_PATH = Path(__file__).resolve().parent.parent / "assets" / "architecture.svg"
+
+_EXPLANATION_MD = """
+### Pourquoi cette architecture ?
+
+**On ne traduit jamais tout le corpus.** Chaque document conserve son texte
+et sa langue d'origine ; seuls des **embeddings multilingues partagés**
+(`BAAI/bge-m3`) projettent toutes les langues dans le même espace
+sémantique, ce qui permet une recherche véritablement **cross-lingue** :
+une question posée en russe retrouve un règlement rédigé en français ou en
+anglais, sans étape de traduction préalable et sans perte de nuance
+juridique ou métier.
+
+**Un seul jeton d'API.** Génération (`DeepSeek-V4.1-Flash`) et embeddings
+passent tous les deux par le routeur **Inference Providers** de Hugging
+Face — un seul `HF_TOKEN` suffit pour l'ensemble de la chaîne, y compris la
+lecture/écriture du dataset privé.
+
+**Le vecteur-store tient dans le Space.** Plutôt qu'un service Qdrant
+externe à héberger séparément, l'index est un fichier Parquet stocké dans
+un **dataset privé Hugging Face** et chargé en mémoire (FAISS) au démarrage
+du Space — zéro dépendance opérationnelle supplémentaire.
+
+**Mode strict.** Si le meilleur score de similarité retourné par la
+recherche est inférieur au seuil de confiance configuré, l'assistant
+s'abstient explicitement plutôt que d'halluciner une réponse.
+"""
+
+
+def build_architecture_tab():
+    with gr.Column():
+        gr.Markdown("### 🏗️ Architecture de PolyglotRAG")
+        svg_content = _SVG_PATH.read_text(encoding="utf-8")
+        gr.HTML(f'<div style="background:white;border-radius:14px;padding:8px;">{svg_content}</div>')
+        gr.Markdown(_EXPLANATION_MD)

core/ui/chat_tab.py

@@ -0,0 +1,121 @@
+"""Onglet Chat : question multilingue, réponse ciblée, citations, mode RTL."""
+from __future__ import annotations
+
+import gradio as gr
+
+from core.ingestion.language_detector import language_label
+from core.pipeline import ask
+from core.retrieval.vector_store import get_vector_store
+from config import SUPPORTED_LANGUAGES
+
+LANGUAGE_CHOICES = [("Automatique (détection)", "auto")] + [
+    (info["name"], code) for code, info in SUPPORTED_LANGUAGES.items()
+]
+LANGUAGE_FILTER_CHOICES = [("Toutes les langues", "all")] + [
+    (info["name"], code) for code, info in SUPPORTED_LANGUAGES.items()
+]
+
+EXAMPLE_QUESTIONS = [
+    "Какой срок возврата средств?",
+    "Quels sont les délais de remboursement ?",
+    "What is the refund deadline?",
+    "¿Cuál es el plazo de reembolso?",
+    "ما هي مدة استرداد الأموال؟",
+    "Qual é o prazo para o reembolso?",
+]
+
+
+def _format_sources_html(sources: list[dict]) -> str:
+    if not sources:
+        return "<em>Aucune source utilisée (réponse d'abstention).</em>"
+    chips = []
+    for s in sources:
+        label = language_label(s["language"])
+        chips.append(
+            f'<span class="pg-source-chip">📄 {s["file"]} · {label} · '
+            f'p.{s["page"]} · score {s["score"]}</span>'
+        )
+    return "".join(chips)
+
+
+def answer_question(
+    question: str,
+    response_language_choice: str,
+    filter_language_choice: str,
+):
+    if not question or not question.strip():
+        return "", "", gr.update(visible=False)
+
+    store = get_vector_store()
+    if not store.is_ready():
+        msg = (
+            "⚠️ L'index documentaire est vide. Lancez d'abord l'ingestion "
+            "(`python scripts/ingest.py`) ou configurez HF_DATASET_REPO."
+        )
+        return msg, "", gr.update(visible=False)
+
+    lang_filter = None if filter_language_choice == "all" else filter_language_choice
+    outcome = ask(question, store, response_language_choice, lang_filter)
+    retrieval, result = outcome.retrieval, outcome.generation
+
+    is_rtl = SUPPORTED_LANGUAGES.get(outcome.target_language, {}).get("dir") == "rtl"
+    answer_html = (
+        f'<div class="{"pg-rtl-answer" if is_rtl else ""}">{result.answer}</div>'
+    )
+    cache_note = " · ⚡ **servi depuis le cache**" if outcome.from_cache else ""
+    meta = (
+        f"Langue détectée de la question : **{language_label(retrieval.query_language)}** "
+        f"(confiance {retrieval.query_language_confidence:.0%}) · "
+        f"Score de confiance retrieval : **{retrieval.confidence_score:.2f}** · "
+        f"Latence totale : **{outcome.retrieval_latency_ms + result.latency_seconds * 1000:.0f} ms**"
+        f"{cache_note}"
+    )
+    sources_html = _format_sources_html(result.sources)
+
+    return answer_html, meta, gr.update(value=sources_html, visible=True)
+
+
+def build_chat_tab():
+    with gr.Column():
+        gr.Markdown(
+            "### 💬 Poser une question — dans n'importe laquelle des 6 langues"
+        )
+        with gr.Row():
+            question_box = gr.Textbox(
+                label="Votre question",
+                placeholder="Posez votre question en EN / FR / RU / ES / AR / PT…",
+                lines=2,
+                scale=4,
+            )
+        with gr.Row():
+            response_lang = gr.Dropdown(
+                choices=LANGUAGE_CHOICES,
+                value="auto",
+                label="Répondre dans la langue du document / Traduire la réponse",
+                info="« Automatique » répond dans la langue de la question.",
+                scale=2,
+            )
+            filter_lang = gr.Dropdown(
+                choices=LANGUAGE_FILTER_CHOICES,
+                value="all",
+                label="Restreindre la recherche à une langue",
+                scale=2,
+            )
+            submit_btn = gr.Button("Rechercher & répondre", variant="primary", scale=1)
+
+        gr.Examples(examples=EXAMPLE_QUESTIONS, inputs=question_box)
+
+        answer_box = gr.HTML(label="Réponse")
+        meta_box = gr.Markdown()
+        sources_box = gr.HTML(visible=False, label="Sources")
+
+        submit_btn.click(
+            answer_question,
+            inputs=[question_box, response_lang, filter_lang],
+            outputs=[answer_box, meta_box, sources_box],
+        )
+        question_box.submit(
+            answer_question,
+            inputs=[question_box, response_lang, filter_lang],
+            outputs=[answer_box, meta_box, sources_box],
+        )

core/ui/theme.py

@@ -0,0 +1,39 @@
+"""CSS partagé — identité visuelle sobre et professionnelle (bleu nuit / or)."""
+
+CUSTOM_CSS = """
+:root {
+    --pg-navy: #0f2942;
+    --pg-navy-2: #1d3557;
+    --pg-gold: #b8860b;
+    --pg-teal: #0ea5a3;
+}
+.gradio-container {
+    font-family: 'Segoe UI', 'Helvetica Neue', Arial, sans-serif !important;
+    max-width: 1280px !important;
+}
+#pg-header {
+    background: linear-gradient(90deg, var(--pg-navy) 0%, var(--pg-navy-2) 100%);
+    color: white;
+    padding: 22px 28px;
+    border-radius: 14px;
+    margin-bottom: 14px;
+}
+#pg-header h1 { margin: 0; font-size: 1.55rem; font-weight: 700; }
+#pg-header p { margin: 6px 0 0 0; color: #c9d6e3; font-size: 0.92rem; }
+.pg-kpi-card {
+    border: 1px solid #e2e8f0;
+    border-radius: 12px;
+    padding: 16px 18px;
+    background: white;
+    box-shadow: 0 1px 3px rgba(15,41,66,0.06);
+}
+.pg-kpi-value { font-size: 1.7rem; font-weight: 800; color: var(--pg-navy); }
+.pg-kpi-label { font-size: 0.82rem; color: #64748b; text-transform: uppercase; letter-spacing: .04em; }
+.pg-rtl-answer { direction: rtl; text-align: right; font-size: 1.05rem; }
+.pg-source-chip {
+    display: inline-block; background: #eef4fb; color: #0f2942;
+    border: 1px solid #cfe0f3; border-radius: 999px; padding: 3px 10px;
+    font-size: 0.78rem; margin: 2px 4px 2px 0;
+}
+footer { visibility: hidden; }
+"""

docker-compose.yml

@@ -0,0 +1,15 @@
+services:
+  polyglot-rag:
+    build: .
+    image: polyglot-rag:latest
+    container_name: polyglot-rag
+    ports:
+      - "7860:7860"
+    env_file:
+      - .env
+    volumes:
+      # Persiste l'index local et la base de métriques entre deux redémarrages
+      # du conteneur (facultatif si vous chargez toujours l'index depuis le
+      # dataset privé Hugging Face via HF_DATASET_REPO).
+      - ./data:/app/data
+    restart: unless-stopped

knowledge_base/ar/سياسة_الاسترجاع_ar.md

@@ -0,0 +1,30 @@
+# سياسة استرداد الأموال
+
+## 1. مهلة الاسترداد
+
+يتم رد المبلغ المدفوع في غضون **15 يوم عمل** كحد أقصى بعد موافقة خدمة
+العملاء على الطلب.
+
+## 2. شروط الأهلية
+
+يكون المنتج مؤهلاً للاسترداد إذا:
+
+- تمت إعادته في عبوته الأصلية؛
+- لم يُستخدم بما يتجاوز الاستخدام التجريبي المعقول؛
+- قُدّم الطلب خلال 30 يومًا من تاريخ التسليم؛
+- تم إرفاق إثبات الشراء (فاتورة أو رقم الطلب).
+
+## 3. طريقة الاسترداد
+
+يتم رد المبلغ بنفس وسيلة الدفع الأصلية. في حال تعذّر ذلك (بطاقة منتهية
+الصلاحية أو حساب مغلق)، يُقترح على العميل رصيد بديل أو تحويل بنكي.
+
+## 4. حالات خاصة
+
+المنتجات المخصصة وتراخيص البرامج المُفعّلة غير قابلة للاسترداد، إلا في
+حال ثبوت عيب تصنيع من قبل فريق الجودة.
+
+## 5. النزاعات
+
+في حال الاعتراض على قرار الاسترداد، يمكن للعميل تصعيد الطلب إلى خدمة
+"العملاء - المستوى الثاني"، الملزمة بالرد خلال 5 أيام عمل.

knowledge_base/en/employee_handbook_en.md

@@ -0,0 +1,33 @@
+# Employee Handbook — Refunds & Expense Policy
+
+## 1. Customer refund requests
+
+Refund requests must be submitted within **30 calendar days** of purchase.
+This 30-day window applies to the submission of the request, not
+necessarily to the timeline of the actual money transfer, which follows the
+standard processing time defined by the finance department (typically
+5-10 business days once the request is approved).
+
+## 2. Approval workflow
+
+1. The customer support agent verifies proof of purchase.
+2. The request is logged in the CRM with a unique ticket ID.
+3. A supervisor approves refunds above $500.
+4. Finance processes the transfer or store credit.
+
+## 3. Employee expense reimbursement
+
+Employees who incur business expenses (travel, client meals, software
+subscriptions) must submit receipts within 15 days. Reimbursement is paid
+with the next payroll cycle after approval.
+
+## 4. Exceptions
+
+Digital goods that have been downloaded or activated are non-refundable,
+except in case of a proven technical defect confirmed by the engineering
+team.
+
+## 5. Escalation
+
+If a refund is contested, employees should escalate to the Tier-2 Customer
+Relations team, which commits to a response within 5 business days.

knowledge_base/es/politica_devoluciones_es.md

@@ -0,0 +1,33 @@
+# Política de reembolso
+
+## 1. Plazo de reembolso
+
+El reembolso se realiza en un plazo máximo de **20 días naturales** tras la
+aprobación de la solicitud por parte del servicio de atención al cliente.
+
+## 2. Condiciones de elegibilidad
+
+Un producto es elegible para reembolso si:
+
+- se devuelve en su embalaje original;
+- no presenta signos de uso más allá de una prueba razonable;
+- la solicitud se realiza dentro de los 30 días posteriores a la entrega;
+- se adjunta un comprobante de compra.
+
+## 3. Método de reembolso
+
+El reembolso se efectúa mediante el mismo método de pago utilizado en la
+compra original. Si no está disponible, se ofrece un vale o transferencia
+bancaria.
+
+## 4. Excepciones
+
+Los productos personalizados y las licencias de software activadas no son
+reembolsables, salvo defecto de fabricación confirmado por el equipo de
+calidad.
+
+## 5. Disputas
+
+En caso de desacuerdo, el cliente puede escalar la solicitud al servicio de
+"Atención al Cliente Nivel 2", que debe responder en un plazo de 5 días
+hábiles.

knowledge_base/fr/politique_remboursement_fr.md

@@ -0,0 +1,35 @@
+# Politique de remboursement
+
+## 1. Délai de remboursement
+
+Le remboursement est effectué dans un délai maximal de **14 jours** après
+l'approbation de la demande par le service client. Ce délai court à partir
+de la date de réception du produit retourné par notre entrepôt, et non à
+partir de la date d'envoi par le client.
+
+## 2. Conditions d'éligibilité
+
+Un produit est éligible au remboursement si :
+
+- il est retourné dans son emballage d'origine ;
+- il n'a pas été utilisé au-delà d'un usage d'essai raisonnable ;
+- la demande est faite dans les 30 jours suivant la livraison ;
+- une preuve d'achat est fournie (facture ou numéro de commande).
+
+## 3. Modes de remboursement
+
+Le remboursement est effectué selon le mode de paiement initial. Si le
+paiement initial n'est plus disponible (carte expirée, compte clos), un
+avoir ou un virement bancaire est proposé.
+
+## 4. Cas particuliers
+
+Les produits personnalisés, les logiciels dont la licence a été activée et
+les biens périssables ne sont pas remboursables, sauf défaut de fabrication
+constaté par notre service qualité.
+
+## 5. Litiges
+
+En cas de désaccord sur un remboursement, le client peut escalader la
+demande auprès du service « Relation Client Niveau 2 », qui dispose de
+5 jours ouvrés pour répondre.

knowledge_base/pt/politica_de_reembolso_pt.md

@@ -0,0 +1,32 @@
+# Política de reembolso
+
+## 1. Prazo de reembolso
+
+O reembolso é efetuado no prazo máximo de **21 dias corridos** após a
+aprovação do pedido pelo serviço de apoio ao cliente.
+
+## 2. Condições de elegibilidade
+
+Um produto é elegível para reembolso se:
+
+- for devolvido na embalagem original;
+- não apresentar sinais de uso além de um teste razoável;
+- o pedido for feito dentro de 30 dias após a entrega;
+- for apresentado um comprovativo de compra.
+
+## 3. Forma de reembolso
+
+O reembolso é realizado através do mesmo método de pagamento utilizado na
+compra original. Caso não seja possível, é oferecido um crédito na loja ou
+transferência bancária.
+
+## 4. Exceções
+
+Produtos personalizados e licenças de software ativadas não são
+reembolsáveis, exceto em caso de defeito de fabrico comprovado pela equipa
+de qualidade.
+
+## 5. Litígios
+
+Em caso de desacordo, o cliente pode escalar o pedido para o serviço de
+"Apoio ao Cliente Nível 2", que tem um prazo de 5 dias úteis para responder.

knowledge_base/ru/faq_ru.md

@@ -0,0 +1,33 @@
+# Часто задаваемые вопросы — Возврат средств
+
+## 1. Срок рассмотрения заявки
+
+Заявка на возврат средств рассматривается в течение **10 рабочих дней**
+с момента получения возвращённого товара на склад. Решение направляется
+клиенту по электронной почте.
+
+## 2. Условия возврата
+
+Товар принимается к возврату, если:
+
+- сохранена оригинальная упаковка;
+- товар не имеет следов эксплуатации;
+- заявка подана в течение 30 дней с момента покупки;
+- предоставлен документ, подтверждающий покупку.
+
+## 3. Способ возврата денежных средств
+
+Деньги возвращаются тем же способом, которым была произведена оплата.
+Если это невозможно (карта заблокирована, счёт закрыт), клиенту
+предлагается возврат на банковские реквизиты.
+
+## 4. Исключения
+
+Персонализированные товары и активированные цифровые лицензии возврату
+не подлежат, за исключением случаев подтверждённого производственного
+брака.
+
+## 5. Эскалация спора
+
+При несогласии с решением клиент может обратиться в службу поддержки
+второго уровня, которая обязана ответить в течение 5 рабочих дней.

pytest.ini

@@ -0,0 +1,4 @@
+[pytest]
+testpaths = tests
+python_files = test_*.py
+addopts = -q

requirements.txt

@@ -0,0 +1,13 @@
+gradio>=4.44,<6
+huggingface_hub>=0.25
+python-dotenv>=1.0
+numpy>=1.26
+pandas>=2.2
+pyarrow>=16.0
+faiss-cpu>=1.8
+lingua-language-detector>=2.0
+pypdf>=4.2
+python-docx>=1.1
+beautifulsoup4>=4.12
+lxml>=5.2
+cachetools>=5.3

scripts/ingest.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""
+CLI d'ingestion : construit l'index (Parquet) à partir de `knowledge_base/`
+et, si `HF_DATASET_REPO` est configuré, le pousse vers le dataset privé
+Hugging Face.
+
+Usage :
+    python scripts/ingest.py
+    python scripts/ingest.py --kb-dir chemin/vers/mes_documents --no-push
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from core.ingestion.indexer import (  # noqa: E402
+    build_chunk_records,
+    push_index_to_hub,
+    save_index_locally,
+)
+from config import settings  # noqa: E402
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Ingestion PolyglotRAG")
+    parser.add_argument("--kb-dir", default="knowledge_base", help="Dossier source")
+    parser.add_argument(
+        "--out-dir", default=settings.local_index_dir, help="Dossier de sortie local"
+    )
+    parser.add_argument(
+        "--no-push", action="store_true", help="Ne pas pousser vers le Hub HF"
+    )
+    args = parser.parse_args()
+
+    errors = settings.validate()
+    if errors:
+        print("⚠️  " + "\n⚠️  ".join(errors))
+
+    kb_dir = Path(args.kb_dir)
+    if not kb_dir.exists():
+        raise SystemExit(f"Dossier introuvable : {kb_dir}")
+
+    def progress(file_name: str, lang: str) -> None:
+        print(f"  ✓ {lang}/{file_name}")
+
+    print(f"📚 Ingestion de '{kb_dir}'…")
+    records = build_chunk_records(kb_dir, progress_cb=progress)
+    print(f"✅ {len(records)} chunks générés.")
+
+    out_dir = Path(args.out_dir)
+    parquet_path = save_index_locally(records, out_dir)
+    print(f"💾 Index local sauvegardé : {parquet_path}")
+
+    if args.no_push:
+        print("⏭️  Push vers le Hub désactivé (--no-push).")
+        return
+
+    if not settings.hf_dataset_repo:
+        print(
+            "ℹ️  HF_DATASET_REPO non défini : l'index reste local uniquement. "
+            "Définissez HF_DATASET_REPO dans .env pour le publier sur le Hub."
+        )
+        return
+
+    print(f"☁️  Publication vers le dataset privé '{settings.hf_dataset_repo}'…")
+    url = push_index_to_hub(out_dir, settings.hf_dataset_repo, settings.hf_token)
+    print(f"✅ Dataset publié : {url}")
+
+
+if __name__ == "__main__":
+    main()

tests/conftest.py

@@ -0,0 +1,56 @@
+"""Fixtures partagées : aucun test ne doit faire d'appel réseau."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import numpy as np
+import pytest
+
+
+def _fake_embed_texts(texts, kind="passage", dim: int = 256):
+    """
+    Embeddings factices, sans aucun appel réseau, mais qui restent
+    topiquement pertinents : sac-de-mots haché (bag-of-hashed-words).
+    Deux textes qui partagent du vocabulaire (même langue, même sujet)
+    obtiennent une similarité cosinus plus élevée que deux textes qui n'en
+    partagent pas (ce qui suffit à tester le classement du retrieval, sans
+    prétendre reproduire un vrai modèle sémantique multilingue).
+    """
+    import hashlib
+    import re
+
+    token_re = re.compile(r"\w+", re.UNICODE)
+    vectors = []
+    for t in texts:
+        vec = np.zeros(dim, dtype="float32")
+        for token in token_re.findall(t.lower()):
+            idx = int(hashlib.md5(token.encode("utf-8")).hexdigest(), 16) % dim
+            vec[idx] += 1.0
+        norm = np.linalg.norm(vec)
+        vectors.append(vec / norm if norm else vec)
+    return np.vstack(vectors)
+
+
+@pytest.fixture
+def fake_embed_fn():
+    """Fonction batch (list[str]) -> list[list[float]] pour l'ingestion."""
+    def _fn(texts):
+        return _fake_embed_texts(texts).tolist()
+    return _fn
+
+
+@pytest.fixture(autouse=True)
+def _no_network_embeddings(monkeypatch):
+    """Empêche tout appel réseau accidentel vers l'API d'embeddings."""
+    import core.retrieval.embeddings as embeddings_module
+
+    def _guard(*_args, **_kwargs):
+        raise AssertionError(
+            "Un test a tenté un appel réseau réel vers l'API d'embeddings — "
+            "utilisez fake_embed_fn / monkeypatch."
+        )
+
+    monkeypatch.setattr(embeddings_module, "embed_texts", _guard, raising=False)

tests/test_chunker.py

@@ -0,0 +1,34 @@
+from core.ingestion.chunker import chunk_text, split_into_sentences
+
+
+def test_split_into_sentences_basic():
+    text = "Phrase un. Phrase deux ! Phrase trois ?"
+    sentences = split_into_sentences(text)
+    assert len(sentences) == 3
+    assert sentences[0] == "Phrase un."
+
+
+def test_split_into_sentences_arabic_punctuation():
+    text = "هذه جملة أولى؟ هذه جملة ثانية."
+    sentences = split_into_sentences(text)
+    assert len(sentences) == 2
+
+
+def test_chunk_text_respects_size_and_overlap():
+    text = " ".join(f"mot{i}." for i in range(200))
+    chunks = chunk_text(text, chunk_size_tokens=50, overlap_tokens=10)
+    assert len(chunks) > 1
+    # chaque chunk (sauf peut-être le dernier) reste proche de la taille cible
+    for c in chunks[:-1]:
+        assert 0 < len(c.text.split()) <= 70
+
+
+def test_chunk_text_empty_returns_single_empty_chunk():
+    chunks = chunk_text("", chunk_size_tokens=100, overlap_tokens=10)
+    assert len(chunks) == 1
+
+
+def test_chunk_text_short_text_single_chunk():
+    chunks = chunk_text("Une phrase courte.", chunk_size_tokens=350, overlap_tokens=60)
+    assert len(chunks) == 1
+    assert "phrase courte" in chunks[0].text

tests/test_indexer.py

@@ -0,0 +1,29 @@
+from pathlib import Path
+
+from core.ingestion.indexer import build_chunk_records, save_index_locally
+
+
+def test_build_chunk_records_covers_all_languages(fake_embed_fn, tmp_path):
+    kb_dir = Path("knowledge_base")
+    records = build_chunk_records(kb_dir, embed_fn=fake_embed_fn)
+
+    assert len(records) >= 6  # au moins un chunk par langue échantillon
+    languages = {r.language for r in records}
+    assert languages == {"en", "fr", "ru", "es", "ar", "pt"}
+
+    # chaque enregistrement porte des métadonnées complètes et un embedding
+    for r in records:
+        assert r.chunk_id
+        assert r.document_id
+        assert r.source_file
+        assert r.text.strip()
+        assert len(r.embedding) > 0
+
+
+def test_save_index_locally_writes_parquet_and_manifest(fake_embed_fn, tmp_path):
+    records = build_chunk_records(Path("knowledge_base"), embed_fn=fake_embed_fn)
+    out_dir = tmp_path / "index"
+    parquet_path = save_index_locally(records, out_dir)
+
+    assert parquet_path.exists()
+    assert (out_dir / "manifest.json").exists()

tests/test_language_detector.py

@@ -0,0 +1,33 @@
+from core.ingestion.language_detector import detect_language, language_label
+
+
+def test_detect_french():
+    lang, conf = detect_language("Quels sont les délais de remboursement ?")
+    assert lang == "fr"
+    assert conf > 0.5
+
+
+def test_detect_russian():
+    lang, conf = detect_language("Какой срок возврата средств?")
+    assert lang == "ru"
+
+
+def test_detect_arabic():
+    lang, conf = detect_language("ما هي مدة استرداد الأموال؟")
+    assert lang == "ar"
+
+
+def test_detect_english():
+    lang, conf = detect_language("What is the refund deadline?")
+    assert lang == "en"
+
+
+def test_detect_empty_text_is_unknown():
+    lang, conf = detect_language("")
+    assert lang == "unknown"
+    assert conf == 0.0
+
+
+def test_language_label_known_and_unknown():
+    assert language_label("fr") == "Français"
+    assert language_label("xx") == "xx"

tests/test_metrics_logger.py

@@ -0,0 +1,39 @@
+from pathlib import Path
+
+from core.metrics import logger as metrics_logger
+
+
+def test_log_query_and_summary(tmp_path, monkeypatch):
+    db_path = tmp_path / "metrics.sqlite3"
+    monkeypatch.setattr(metrics_logger.settings, "metrics_db_path", str(db_path))
+
+    metrics_logger.log_query(
+        question="Quels sont les délais de remboursement ?",
+        query_language="fr",
+        target_language="fr",
+        confidence_score=0.8,
+        is_sufficient=True,
+        used_fallback=False,
+        retrieval_latency_ms=120.0,
+        generation_latency_ms=450.0,
+        sources=[{"file": "a.pdf", "language": "fr", "page": 1, "score": 0.8}],
+    )
+    metrics_logger.log_query(
+        question="Какой срок?",
+        query_language="ru",
+        target_language="ru",
+        confidence_score=0.1,
+        is_sufficient=False,
+        used_fallback=True,
+        retrieval_latency_ms=90.0,
+        generation_latency_ms=0.0,
+        sources=[],
+    )
+
+    summary = metrics_logger.summary_metrics()
+    assert summary["total_queries"] == 2
+    assert summary["abstention_rate"] == 0.5
+    assert "fr" in summary["by_query_language"]
+
+    recent = metrics_logger.fetch_recent(limit=10)
+    assert len(recent) == 2

tests/test_pipeline.py

@@ -0,0 +1,96 @@
+"""
+Vérifie l'optimisation de cache au niveau de `core.pipeline.ask` : une
+même question (identique, même langue de réponse, même filtre) posée deux
+fois ne doit déclencher qu'UN SEUL appel à la recherche et à la génération.
+"""
+from __future__ import annotations
+
+import core.pipeline as pipeline
+from core.generation.answer_generator import GenerationResult
+from core.metrics import logger as metrics_logger
+from core.retrieval.hybrid_search import RetrievalResult
+from core.retrieval.vector_store import SearchHit
+
+
+def _isolate_metrics_db(monkeypatch, tmp_path):
+    monkeypatch.setattr(
+        metrics_logger.settings, "metrics_db_path", str(tmp_path / "metrics.sqlite3")
+    )
+
+
+def _fake_retrieval() -> RetrievalResult:
+    hit = SearchHit(
+        chunk_id="fr_x_p1_c0",
+        document_id="fr_x",
+        source_file="x.md",
+        page=1,
+        language="fr",
+        title="X",
+        text_direction="ltr",
+        text="Le remboursement est effectué sous 14 jours.",
+        score=0.9,
+    )
+    return RetrievalResult(
+        hits=[hit],
+        query_language="fr",
+        query_language_confidence=0.95,
+        confidence_score=0.9,
+        is_sufficient=True,
+    )
+
+
+def test_ask_uses_cache_on_repeated_question(monkeypatch, tmp_path):
+    _isolate_metrics_db(monkeypatch, tmp_path)
+    pipeline.answer_cache.clear()
+    call_counter = {"retrieve": 0, "generate": 0}
+
+    def fake_retrieve(question, store, language_filter=None, forced_query_language=None):
+        call_counter["retrieve"] += 1
+        return _fake_retrieval()
+
+    def fake_generate_answer(question, retrieval, target_language):
+        call_counter["generate"] += 1
+        return GenerationResult(
+            answer="Réponse factice.",
+            used_fallback=False,
+            latency_seconds=0.01,
+            sources=[{"file": "x.md", "language": "fr", "page": 1, "score": 0.9}],
+        )
+
+    monkeypatch.setattr(pipeline, "retrieve", fake_retrieve)
+    monkeypatch.setattr(pipeline, "generate_answer", fake_generate_answer)
+
+    store = object()  # non utilisé par les fakes ci-dessus
+
+    first = pipeline.ask("Quels sont les délais ?", store, "auto", None)
+    second = pipeline.ask("Quels sont les délais ?", store, "auto", None)
+
+    assert first.from_cache is False
+    assert second.from_cache is True
+    assert call_counter["retrieve"] == 1
+    assert call_counter["generate"] == 1
+    assert second.generation.answer == "Réponse factice."
+
+
+def test_ask_does_not_reuse_cache_for_different_language_filter(monkeypatch, tmp_path):
+    _isolate_metrics_db(monkeypatch, tmp_path)
+    pipeline.answer_cache.clear()
+    call_counter = {"retrieve": 0}
+
+    def fake_retrieve(question, store, language_filter=None, forced_query_language=None):
+        call_counter["retrieve"] += 1
+        return _fake_retrieval()
+
+    def fake_generate_answer(question, retrieval, target_language):
+        return GenerationResult(
+            answer="Réponse.", used_fallback=False, latency_seconds=0.01, sources=[]
+        )
+
+    monkeypatch.setattr(pipeline, "retrieve", fake_retrieve)
+    monkeypatch.setattr(pipeline, "generate_answer", fake_generate_answer)
+
+    store = object()
+    pipeline.ask("Question ?", store, "auto", None)
+    pipeline.ask("Question ?", store, "auto", "fr")
+
+    assert call_counter["retrieve"] == 2

tests/test_prompts.py

@@ -0,0 +1,41 @@
+from core.generation.prompts import build_messages, format_context, no_context_message
+from core.retrieval.vector_store import SearchHit
+
+
+def _sample_hits():
+    return [
+        SearchHit(
+            chunk_id="fr_refund_p04_c03",
+            document_id="refund_policy_fr",
+            source_file="politique_remboursement_fr.pdf",
+            page=4,
+            language="fr",
+            title="Politique de remboursement",
+            text_direction="ltr",
+            text="Le remboursement est effectué dans un délai maximal de 14 jours.",
+            score=0.81,
+        )
+    ]
+
+
+def test_format_context_includes_language_and_page():
+    ctx = format_context(_sample_hits())
+    assert "Langue : fr" in ctx
+    assert "Page : 4" in ctx
+    assert "14 jours" in ctx
+
+
+def test_build_messages_targets_requested_language():
+    messages = build_messages("Какой срок?", _sample_hits(), target_language="ru")
+    assert messages[0]["role"] == "system"
+    assert "Русский" in messages[0]["content"]
+    assert "Какой срок?" in messages[1]["content"]
+
+
+def test_no_context_message_falls_back_to_english_for_unknown_language():
+    msg = no_context_message("de")  # allemand non supporté
+    assert msg == no_context_message("en")
+
+
+def test_no_context_message_is_localized():
+    assert "délais" not in no_context_message("ar")