---
title: Corrective RAG Data Assistant
emoji: 🧭
colorFrom: gray
colorTo: green
sdk: docker
app_port: 7860
pinned: false
---

# Corrective RAG Data Assistant

Assistant d'analyse documentaire utilisant un pipeline **Corrective RAG (CRAG)** :
évaluation de pertinence, filtrage, réécriture de requête, routage SQL sécurisé,
génération sourcée et vérification (faithfulness). Si les preuves manquent, le
système refuse plutôt que d'inventer.

Conforme à `Rag_crag.md`, déployable en **Docker** sur un Hugging Face Space,
LLM **deepseek-ai/DeepSeek-V4.1-Flash**.

## Architecture

```
Question utilisateur
        │
        ▼
1. Recherche vectorielle (embeddings fastembed)
        │
        ▼
2. Évaluateur de pertinence (LLM structuré)
        │
        ├── CORRECT ───► Filtrage → génération sourcée
        ├── AMBIGUOUS ─► Réécriture → SQL + re-retrieval → fusion
        └── INCORRECT ─► SQL sécurisé → réponse ou refus
                                      │
                                      ▼
                         Vérification faithfulness (+ boucle)
```

LangGraph (`app/crag/graph.py`) : `retrieve_internal`, `grade_documents`,
`refine_context`, `rewrite_question`, `search_external`, `merge_context`,
`generate_answer`, `verify_answer`.

## Stack (alignée Rag_crag.md)

| Brique | Implémentation |
|---|---|
| Documents | MD / PDF / CSV (`data/policies`, `data/reports`, `data/faq`) |
| Données chiffrées | CSV + **SQLite** `data/database/company.db` |
| SQL | `app/sql/` — SELECT only, whitelist tables/colonnes, LIMIT 100, audit log |
| Embeddings | **fastembed** (ONNX, CPU) `paraphrase-multilingual-MiniLM-L12-v2` ; repli TF-IDF si indisponible |
| LLM | DeepSeek via HF Inference API (ou `mock` pour CI) |
| UI | FastAPI + static HTML/CSS/JS |
| Eval | **60** questions annotées (`eval/eval_questions.json`) |

> SQL Server de production n'est pas hébergeable sur un Space HF : SQLite en
> lecture seule applique les **mêmes règles de sécurité** (pas de SQL libre,
> validateur, whitelist).

## Démarrage local

```bash
cp .env.example .env
# HF_TOKEN + LLM_PROVIDER=hf pour de vraies réponses
# EMBEDDING_BACKEND=auto (défaut) ou tfidf pour CI offline

docker compose up --build
# UI : http://localhost:7860
```

Sans Docker :

```bash
python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements-dev.txt
python scripts/build_data_assets.py   # PDF + company.db
uvicorn app.main:app --reload --port 7860
pytest tests/ -v
python eval/evaluate.py
```

## Métriques

`eval/evaluate.py` compare Corrective RAG vs RAG classique naïf sur 60
questions (context precision/recall, faithfulness, answer relevancy,
abstention accuracy, SQL execution accuracy, fallback/correction rate).

Résultats dans l'onglet **Évaluation** (`GET /api/metrics`).

## Structure

```
corrective-rag-data-assistant/
├── app/
│   ├── api/routes.py
│   ├── core/{config,security}.py
│   ├── crag/          # pipeline LangGraph
│   ├── sql/           # validator, router, executor, seed
│   └── ingestion/     # loaders multi-formats + indexer embeddings
├── data/
│   ├── policies/      # .md + .pdf
│   ├── reports/       # .csv + .md/.pdf
│   ├── faq/           # .md
│   └── database/company.db
├── eval/              # 60 questions + evaluate.py
├── static/
├── tests/
├── scripts/
└── Rag_crag.md
```

## Limites

- **SQL Server** non hébergé sur HF Space → SQLite local équivalent sécurisé.
- **Embeddings** : premier démarrage télécharge le modèle ONNX (~80–120 Mo).
- **NL→SQL** : heuristique whitelistée (démo), pas un parseur NL2SQL production.
- **Métriques mock** non représentatives tant que `LLM_PROVIDER=mock`.