rag-banking-regulatory-agent

# 🏦 RAG Banking Regulatory Agent — V.2.0 (POC Industrialisé)       > **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](./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) ```bash # 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 ```bash 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) ```bash 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 ```bash # 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`) : ```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` : ```json [{"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](./SECURITY.md) | Politique de sécurité et risques connus (POC) | | [CONTRIBUTING.md](./CONTRIBUTING.md) | Guide de contribution et standards de code | | [.env.example](./.env.example) | Variables d'environnement (avec avertissements) | | [guide\_local\_use.md](./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.