RAG Banking Regulatory Server

Agent IA orchestrant plusieurs LLM gratuits (Ollama, Gemini) sur un corpus de réglementation bancaire française/européenne, avec support MCP (serveur + client) et déploiement cloud-ready (Docker, Kubernetes, CI/CD, monitoring).

⚠️ Statut : POC / Démonstration technique. Ce projet illustre des patterns d'ingénierie IA (RAG hybride, routage LLM, MCP, observabilité). Il n'est pas destiné à un usage en production bancaire sans revue de sécurité complémentaire. Voir SECURITY.md.

Ce projet part d'un pipeline RAG simple (scripts ingest.py / query.py / evaluate.py) et le transforme en agent industrialisé :

• 🧠 Orchestration LLM : routage intelligent + fallback automatique entre Ollama (gratuit, local), Gemini (palier gratuit) et OpenAI (optionnel, payant)
• 🔌 MCP (Model Context Protocol) : le RAG est exposé comme serveur MCP (utilisable depuis Claude Desktop ou tout client MCP), et l'agent peut consommer des serveurs MCP externes comme outils
• 🌐 API REST (FastAPI) avec authentification par clé, endpoints de santé et métriques Prometheus
• 🐳 Conteneurisation complète (Docker multi-stage, docker-compose)
• ☸️ Cloud-ready : manifestes Kubernetes (Deployment, HPA, PDB, Ingress, ConfigMap/Secret)
• 🔁 CI/CD : GitHub Actions (lint → tests → build → push registre → déploiement K8s)
• 📊 Observabilité : logs structurés JSON (structlog), métriques Prometheus, dashboards Grafana

---

🏗️ Architecture

                         ┌─────────────────────────────────────────┐
                         │              Clients                     │
                         │   API REST · Claude Desktop (MCP) ·      │
                         │   Autres agents MCP                      │
                         └───────────────┬───────────────────────────┘
                                         │
              ┌──────────────────────────┼──────────────────────────┐
              ▼                          ▼                          │
   ┌───────────────────┐     ┌────────────────────────┐             │
   │  API FastAPI       │     │  Serveur MCP            │             │
   │  /query /ingest     │     │  rag_search / rag_answer│             │
   │  /health  /metrics  │     └────────────┬────────────┘             │
   └──────────┬──────────┘                  │                          │
              └──────────────┬──────────────┘                          │
                             ▼                                         │
                  ┌─────────────────────────┐        ┌──────────────────────────┐
                  │   Orchestrateur (Agent)  │◀──────▶│  Client MCP (outils       │
                  │  - retrieval RAG         │        │  externes : web, fichiers,│
                  │  - sélection d'outil      │        │  Slack, Drive...)         │
                  │  - construction prompt    │        └──────────────────────────┘
                  └────────────┬──────────────┘
                               ▼
                  ┌─────────────────────────┐
                  │   RAG Retriever          │
                  │  FAISS (dense) + BM25    │
                  │  (sparse) → RRF fusion   │
                  └────────────┬──────────────┘
                               ▼
                  ┌─────────────────────────────────────┐
                  │           LLM Router                  │
                  │  Stratégie: cost_first / quality_first│
                  │  Ollama (gratuit) → Gemini → OpenAI   │
                  │  Fallback automatique en cascade      │
                  └───────────────┬───────────────────────┘
                                  ▼
                        Réponse citant ses sources
                        [Document.pdf, p. X]

Décision de routage LLM

Le LLMRouter (src/rag_agent/llm/router.py) choisit le backend selon LLM_ROUTING_STRATEGY :

Stratégie	Ordre d'essai	Cas d'usage
cost_first (défaut)	Ollama → Gemini → OpenAI	Minimiser les coûts, tout en gardant un filet de sécurité qualité
quality_first	Gemini → Ollama → OpenAI	Prioriser la qualité de réponse
ollama_only	Ollama uniquement	Confidentialité maximale (aucune donnée ne sort du réseau local)
gemini_only	Gemini uniquement	Pas d'infrastructure Ollama disponible
round_robin	Alterne à chaque appel	Répartition de charge / comparaison A/B

Si le backend prioritaire échoue (indisponible, timeout, quota dépassé), le router retente automatiquement le suivant dans la cascade — chaque tentative est journalisée (llm_provider_failed, llm_call_succeeded) pour l'observabilité.

---

📂 Structure du projet

rag-banking-agent/
├── src/rag_agent/
│   ├── config.py                # Configuration centralisée (pydantic-settings)
│   ├── logging_config.py        # Logs structurés JSON (structlog)
│   ├── cli.py                   # CLI unifié (ingest/query/evaluate/serve/mcp-serve)
│   ├── llm/                     # ── Orchestration LLM ──
│   │   ├── base.py              #   Interface commune (Strategy pattern)
│   │   ├── ollama_provider.py   #   Backend gratuit local
│   │   ├── gemini_provider.py   #   Backend API gratuit
│   │   ├── openai_provider.py   #   Backend optionnel (payant)
│   │   └── router.py            #   Choix + fallback automatique
│   ├── rag/                     # ── Pipeline RAG ──
│   │   ├── ingest.py            #   Parsing → chunking → embeddings → FAISS
│   │   ├── retrieval.py         #   Dense + BM25 + RRF
│   │   └── prompts.py           #   Prompt système (citation + abstention)
│   ├── agent/                   # ── Orchestrateur ──
│   │   ├── orchestrator.py      #   RAG + outils + LLM router, façade unique
│   │   └── tools.py             #   Registre d'outils (RAG, MCP externes)
│   ├── mcp/                     # ── Model Context Protocol ──
│   │   ├── server.py            #   Expose le RAG comme serveur MCP
│   │   └── client.py            #   Consomme des serveurs MCP externes
│   ├── api/                     # ── API REST ──
│   │   ├── main.py, routes/, schemas.py, metrics.py, dependencies.py
│   └── evaluation/               # ── Évaluation ──
│       ├── test_set.py          #   15 questions de test
│       └── evaluate.py          #   Precision@k + fidélité + provider utilisé
├── tests/                        # Tests unitaires + intégration API (pytest)
├── deploy/
│   ├── docker/                  # Dockerfiles (API + MCP), multi-stage
│   ├── docker-compose.yml       # Environnement complet local
│   ├── k8s/                     # Manifestes Kubernetes (cloud-ready)
│   └── monitoring/              # Config Prometheus
├── .github/workflows/ci-cd.yml  # Pipeline complet
├── scripts/download_corpus.py   # Téléchargement + génération corpus synthétique
├── Makefile                      # Raccourcis de commandes
└── requirements.txt / requirements-dev.txt

---

🚀 Démarrage rapide (local, sans Docker)

# 1. Installation (Linux/Mac)
python -m venv .venv && source .venv/bin/activate
make install-dev

# Windows :
# python -m venv .venv && .venv\Scripts\Activate.ps1
# pip install -r requirements.txt

# 2. Configuration
cp .env.example .env
# Éditer .env : renseigner GEMINI_API_KEY (palier gratuit sur https://aistudio.google.com/apikey)
# et/ou installer Ollama (https://ollama.com) + `ollama pull mistral`

# 3. Préparer le corpus
make download-corpus

# 4. Indexer
make ingest

# 5. Interroger l'agent en CLI
make query Q="Quel est le ratio minimum de CET1 imposé par Bâle III ?"

# 6. Lancer l'API
make serve
# → http://localhost:8000/docs (Swagger UI)

# 7. Lancer le serveur MCP (ex: pour Claude Desktop)
make mcp-serve

Évaluation

make evaluate
# → Precision@k, score de fidélité (recouvrement de mots-clés), taux d'abstention,
#   répartition de l'usage par provider LLM (utile pour arbitrer coût/qualité)

---

🐳 Démarrage avec Docker Compose (API + MCP + Ollama + monitoring)

export GEMINI_API_KEY=your_key_here   # optionnel mais recommandé en secours
docker compose -f deploy/docker-compose.yml up --build -d

# Télécharger le modèle Ollama dans le conteneur
docker compose -f deploy/docker-compose.yml exec ollama ollama pull mistral

# Indexer le corpus (monté dans le conteneur API)
curl -X POST localhost:8000/ingest

# Interroger
curl -X POST localhost:8000/query -H "Content-Type: application/json" \
  -d '{"question": "Quelles sont les obligations LCB-FT des banques françaises ?"}'

Accès :

• API + Swagger : http://localhost:8000/docs
• Prometheus : http://localhost:9090
• Grafana : http://localhost:3000 (admin/admin)
• Serveur MCP (SSE) : http://localhost:8765

---

☸️ Déploiement Kubernetes

# 1. Construire et pousser les images (ou laisser le CI/CD s'en charger)
docker build -f deploy/docker/Dockerfile -t ghcr.io/your-org/rag-banking-agent-api:latest .
docker build -f deploy/docker/Dockerfile.mcp -t ghcr.io/your-org/rag-banking-agent-mcp:latest .

# 2. Configurer les secrets (NE PAS committer les valeurs réelles)
cp deploy/k8s/secret.example.yaml deploy/k8s/secret.yaml
# éditer secret.yaml avec les vraies clés, puis :
kubectl apply -f deploy/k8s/secret.yaml

# 3. Déployer le reste
make k8s-apply

Le déploiement inclut :

• 2 replicas minimum de l'API avec HorizontalPodAutoscaler (2→8 selon CPU/mémoire)
• PodDisruptionBudget pour rester disponible pendant les mises à jour de nœuds
• Liveness/Readiness probes sur /health/live et /health/ready
• PersistentVolumeClaims partagés (ReadWriteMany) pour l'index FAISS et le corpus
• Ingress TLS (via cert-manager) pour l'exposition externe
• Le pipeline CI/CD (.github/workflows/ci-cd.yml) automatise build/push/déploiement à chaque merge sur main

---

🔌 Utilisation via MCP

Comme serveur MCP (le RAG exposé à Claude Desktop ou tout client MCP)

Ajouter dans la configuration MCP du client (ex: claude_desktop_config.json) :

{
  "mcpServers": {
    "rag-banking-regulatory": {
      "command": "python",
      "args": ["-m", "rag_agent.mcp.server"],
      "env": { "PYTHONPATH": "/chemin/vers/rag-banking-agent/src" }
    }
  }
}

Deux outils sont alors disponibles : rag_search (extraits bruts + sources) et rag_answer (réponse complète avec citations).

Comme client MCP (l'agent utilise des outils externes)

Configurer MCP_CLIENT_SERVERS_JSON dans .env :

[{"name": "filesystem", "url": "http://localhost:8001/sse"}]

L'agent peut alors enregistrer un Tool (voir agent/tools.py) qui invoque ce serveur via MCPClientManager.call_tool(...), et le déclencher automatiquement selon des mots-clés (extensible vers un routage piloté par LLM/function-calling).

---

⚠️ Limites connues et pistes d'évolution

Limite	Détail	Piste
Routage par mots-clés	Le choix d'outil MCP est heuristique, pas piloté par le LLM	Passer à un function-calling structuré (JSON schema) piloté par le LLM
Corpus de démo	~5 documents synthétiques + 2 PDF publics	Étendre à un corpus réel de circulaires ACPR
Ingestion synchrone	/ingest bloque la requête HTTP	Passer en job asynchrone (Celery/Argo Workflows) avec suivi de statut
Ollama en K8s	Nécessite un nœud avec assez de CPU/RAM (voire GPU)	Prévoir un nodeSelector/GPU pool dédié pour les modèles plus lourds
Pas de cache de réponses	Chaque question relance retrieval + LLM	Ajouter un cache sémantique (Redis + embeddings) pour les questions fréquentes
FAISS IndexFlatIP	Recherche exhaustive O(n)	Passer à IndexIVFFlat ou HNSW pour +100K vecteurs

📂 Fichiers importants

Fichier	Rôle
SECURITY.md	Politique de sécurité et risques connus (POC)
CONTRIBUTING.md	Guide de contribution et standards de code
.env.example	Variables d'environnement (avec avertissements)
guide_local_use.md	Guide d'utilisation locale + 6 flux I/O détaillés

📜 Licence & Sources

• Code : MIT
• Corpus : documents publics (ACPR, Banque de France, EBA) + documents synthétiques clairement labellisés Synthetic_*. Aucune donnée client ou confidentielle.