🏥 Système Multi-Agents Médical avec LangGraph

Projet Académique — Ingénierie Informatique

Système d'orientation clinique préliminaire utilisant une architecture multi-agents orchestrée par LangGraph, avec un workflow Human-in-the-Loop pour la validation médicale.

⚠️ Ce système ne remplace pas une consultation médicale. Il fournit uniquement une orientation préliminaire à titre indicatif.

---

📋 Table des Matières

• Architecture
• Technologies
• Fonctionnement
• Installation
• Lancement
• API Documentation
• Tests
• Docker
• Structure du Projet

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                     Frontend (React)                     │
│          Tailwind CSS · 4 Écrans · PDF Export            │
└───────────────────────┬─────────────────────────────────┘
                        │ HTTP / REST
┌───────────────────────┴─────────────────────────────────┐
│                   FastAPI (Backend)                       │
│    POST /consultation/start   POST /consultation/resume  │
│    POST /consultation/answer  GET /consultation/{id}     │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────┴─────────────────────────────────┐
│               LangGraph StateGraph                       │
│                                                          │
│  START → Supervisor → DiagnosticAgent ─┐                 │
│                                        ↓                 │
│                               ask_patient() x5           │
│                                        ↓                 │
│                           recommend_interim_care()       │
│                                        ↓                 │
│          Supervisor → PhysicianReview (HITL) ─┐          │
│                                               ↓          │
│                    Supervisor → ReportAgent → END         │
└──────────────────────────────────┬───────────────────────┘
                                   │
                    ┌──────────────┴──────────────┐
                    │  SQLite    │   MCP Server    │
                    │ (persist)  │  (références)   │
                    └─────────────────────────────┘

---

🔧 Technologies

Composant	Technologie
Orchestration	LangGraph + LangChain
LLM	OpenAI GPT-4o
Backend	FastAPI (Python 3.11)
Frontend	React 18 + Tailwind CSS 3
Base de données	SQLite + SQLAlchemy (async)
Intégration	MCP (Model Context Protocol)
PDF	ReportLab
Conteneurisation	Docker + Docker Compose

---

🔄 Fonctionnement

Agents

Agent	Rôle
Supervisor	Orchestre le workflow, décide le prochain agent
DiagnosticAgent	Pose 5 questions, génère synthèse clinique + recommandations
PhysicianReview	Human-in-the-Loop — le médecin valide et ajoute son avis
ReportAgent	Génère le rapport final structuré

Workflow détaillé

1. Patient remplit le formulaire (nom, âge, sexe, symptômes)
2. DiagnosticAgent pose 5 questions cliniques progressives
3. L'agent génère une synthèse clinique préliminaire
4. L'agent génère des recommandations prudentes (repos, hydratation, surveillance)
5. Le workflow s'interrompt — en attente du médecin (Human-in-the-Loop)
6. Le médecin examine les données et ajoute son traitement + conduite à tenir
7. ReportAgent compile le rapport final avec disclaimer
8. Le patient peut télécharger le PDF

---

🚀 Installation

Prérequis

• Python 3.11+
• Node.js 18+
• npm
• Clé API OpenAI

Backend

cd backend

# Créer un environnement virtuel
python -m venv venv
source venv/bin/activate    # macOS/Linux
# venv\Scripts\activate     # Windows

# Installer les dépendances
pip install -r requirements.txt

# Configurer les variables d'environnement
cp .env.example .env
# Éditer .env et ajouter votre OPENAI_API_KEY

Frontend

cd frontend

# Installer les dépendances
npm install

MCP Server

cd mcp_server
pip install mcp

---

▶️ Lancement

Option 1 : Sans Docker

Terminal 1 — Backend :

cd backend
source venv/bin/activate
uvicorn app.api:app --reload --port 8000

Terminal 2 — Frontend :

cd frontend
npm run dev

Terminal 3 — MCP Server (optionnel) :

cd mcp_server
python server.py

Ouvrir : http://localhost:3000

Option 2 : Avec Docker

# Configurer .env
cp backend/.env.example backend/.env
# Éditer backend/.env

# Lancer tout
docker-compose up --build

Ouvrir : http://localhost:3000

---

📡 API Documentation

Route	Méthode	Description
/sessions/start	POST	Créer une nouvelle session
/consultation/start	POST	Démarrer la consultation avec les infos patient
/consultation/answer	POST	Soumettre la réponse du patient
/consultation/resume	POST	Soumettre l'avis du médecin (HITL)
/consultation/{thread_id}	GET	État actuel de la consultation
/consultation/{thread_id}/report	GET	Rapport final
/consultation/{thread_id}/report/pdf	GET	Télécharger le PDF
/consultations/history	GET	Historique des consultations
/health	GET	Health check

Swagger UI

Après lancement du backend : http://localhost:8000/docs

---

🧪 Tests

cd backend
source venv/bin/activate

# Lancer tous les tests
pytest tests/ -v

# Tests spécifiques
pytest tests/test_agents.py -v     # Tests des agents
pytest tests/test_api.py -v        # Tests API
pytest tests/test_graph.py -v      # Tests du graphe

---

🐳 Docker

# Build et lancement
docker-compose up --build

# Arrêt
docker-compose down

# Logs
docker-compose logs -f backend

---

📁 Structure du Projet

AiDistr/
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── api.py                 # Routes FastAPI
│   │   ├── graph.py               # LangGraph workflow
│   │   ├── state.py               # État partagé (MedicalState)
│   │   ├── pdf_generator.py       # Export PDF ReportLab
│   │   ├── nodes/
│   │   │   ├── supervisor.py      # Agent Supervisor
│   │   │   ├── diagnostic_agent.py # Agent Diagnostic (5 questions)
│   │   │   ├── physician_review.py # Revue Médecin (HITL)
│   │   │   └── report_agent.py    # Agent Rapport Final
│   │   ├── tools/
│   │   │   ├── patient_tools.py   # ask_patient()
│   │   │   ├── care_tools.py      # recommend_interim_care()
│   │   │   └── mcp_client.py      # Client MCP
│   │   └── database/
│   │       ├── models.py          # SQLAlchemy models
│   │       └── crud.py            # Opérations CRUD
│   ├── tests/
│   │   ├── test_agents.py
│   │   ├── test_api.py
│   │   └── test_graph.py
│   ├── Dockerfile
│   ├── langgraph.json
│   ├── requirements.txt
│   └── .env.example
├── mcp_server/
│   ├── server.py                  # FastMCP server
│   ├── Dockerfile
│   └── data/
│       ├── symptoms.json          # Base de symptômes
│       └── icd10.json             # Codes ICD-10
├── frontend/
│   ├── src/
│   │   ├── main.jsx
│   │   ├── App.jsx                # Routeur principal
│   │   ├── index.css              # Styles globaux
│   │   ├── api/
│   │   │   └── client.js          # Client API
│   │   └── components/
│   │       ├── PatientForm.jsx    # Écran 1 — Formulaire patient
│   │       ├── ChatConsultation.jsx # Écran 2 — Chat Q&A
│   │       ├── PhysicianReview.jsx # Écran 3 — Revue médecin
│   │       └── FinalReport.jsx    # Écran 4 — Rapport final
│   ├── Dockerfile
│   ├── index.html
│   ├── package.json
│   ├── tailwind.config.js
│   ├── postcss.config.js
│   └── vite.config.js
├── docker-compose.yml
└── README.md

---

📊 Diagrammes

Diagramme LangGraph

START → Supervisor → DiagnosticAgent → ask_patient() (x5)
                                     → recommend_interim_care()
                   → Supervisor → PhysicianReview (HITL - Interrupt)
                   → Supervisor → ReportAgent → END

Diagramme de Séquence

Patient          Frontend         Backend/LangGraph      Médecin
  │                │                    │                   │
  │── Formulaire ─►│── POST /start ────►│                   │
  │                │◄── Question 1 ─────│                   │
  │── Réponse 1 ──►│── POST /answer ───►│                   │
  │                │◄── Question 2 ─────│                   │
  │   ... (x5) ... │                    │                   │
  │                │◄── Synthèse ───────│                   │
  │                │                    │── INTERRUPT ──────►│
  │                │                    │                   │
  │                │                    │◄── Avis médical ──│
  │                │◄── Rapport ────────│                   │
  │── Voir PDF ───►│                    │                   │

---

📝 Licence

Projet académique — Usage éducatif uniquement.

---

⚠️ Avertissement

Ce système ne remplace pas une consultation médicale. Il est conçu à des fins académiques et ne doit pas être utilisé pour des décisions médicales réelles. Consultez toujours un professionnel de santé qualifié.