Mise en place locale (Chatbot)

Prérequis

Python 3.13+
Accès à une base PostgreSQL avec le schéma nAI'vi (files, chunks, qa_pair, roles, indexes…)
Une clé API Mistral valide
Le serveur (apps/server) doit être démarré pour que les rôles par défaut soient initialisés

Variables d'environnement

Créez un fichier .env dans apps/chatbot/ :

# Obligatoire
MISTRAL_API_KEY=xxxx
DATABASE_URL=postgresql://user:password@host:5432/dbname

# Prompts (personnalisables)
CHAINLIT_SYSTEM_PROMPT="You are a helpful AI assistant."
BOT_SYSTEM_PROMPT="Context: {context}\n\nExamples: {few_shots_examples}\n\nQuestion: {question}"
WEB_APP_BASE_URL=http://localhost:3001

# RAG (optionnel, valeurs par défaut utilisées si absent)
RAG_K_CHUNKS=5
RAG_N_EXAMPLES=4

# Auth Chainlit (obligatoire si OAuth activé)
CHAINLIT_AUTH_SECRET=changeme

Les variables sont lues par config/config.py (get_mistral_api_key(), get_db_config()).

Le client Mistral et la connexion DB sont initialisés à la première question (lazy-init), pas au démarrage de Chainlit.

Installation (mode développement)

Depuis apps/chatbot/ :

# Windows PowerShell
. .venv/Scripts/Activate.ps1
# macOS/Linux
source .venv/bin/activate

python -m pip install -e .

Lancer l'interface Chainlit

# Depuis apps/chatbot/
chainlit run src/chatbot/interfaces/chainlit/app.py -w

# Depuis la racine
chainlit run apps/chatbot/src/chatbot/interfaces/chainlit/app.py -w

Interface disponible sur http://localhost:8501 (port configuré dans Dockerfile / docker-compose.yml).

Lancer l'Index API (service séparé)

L'Index API expose POST /regenerate-index appelé par le serveur après un upload de fichiers.

# Depuis apps/chatbot/
uvicorn src.chatbot.interfaces.api.index_api:app --host 0.0.0.0 --port 8502 --reload

La régénération d'index est déclenchée par le bouton admin dans l'interface web, qui appelle la procédure ORPC regenerateIndex. Cela contacte l'INDEX_API_URL configuré dans le serveur.

Workflow de premier démarrage

Démarrer le server (initialise les rôles admin et user en DB).
Uploader des fichiers et annoter les chunks via l'interface web.
Assigner des tags aux chunks, associer les tags aux rôles.
Déclencher la régénération d'index via l'interface web (ou POST /regenerate-index directement).
Démarrer Chainlit → poser une première question → le cache FAISS se charge depuis la DB.

Débogage courant

Problème	Cause probable	Solution
`MISTRAL_API_KEY not found`	Variable absente	Vérifier `.env` et `config/config.py`
Index FAISS vide / pas de réponse	Aucun index en DB	Déclencher `regenerateIndex` depuis web
Erreur de connexion DB	`DATABASE_URL` invalide	Vérifier l'URL et que le serveur Postgres est démarré
`ROLE_INDEX_CACHE` miss constant	Rôle introuvable pour l'user	Vérifier que l'utilisateur a un rôle applicatif assigné

Chatbot Local Setup