Configuration du Chatbot

Cette page centralise toutes les variables d'environnement et paramètres de configuration du chatbot.

Variables d'environnement — Obligatoires

# API Mistral (obligatoire)
MISTRAL_API_KEY=xxxx

# Base de données PostgreSQL — Option 1: URL complète
DATABASE_URL=postgresql://user:password@host:5432/dbname
# Option 2: variables séparées (fallback si DATABASE_URL absent)
DB_NAME=dbname
DB_USER=user
DB_PASSWORD=password
DB_HOST=host
DB_PORT=5432

get_mistral_api_key() déclenche une erreur fatale si MISTRAL_API_KEY est absent.
get_db_config() parse DATABASE_URL en priorité, sinon compose depuis les variables séparées.

Variables d'environnement — Chatbot / Prompts

Variable	Default	Description
`BOT_SYSTEM_PROMPT`	template interne	Template du prompt RAG. Doit contenir `{context}`, `{few_shots_examples}`, `{question}`
`CHAINLIT_SYSTEM_PROMPT`	`"You are a helpful AI assistant."`	Prompt système injecté dans l'historique de conversation Chainlit
`WEB_APP_BASE_URL`	`""`	URL de base de l'app web (pour les liens sources admin, ex: `https://naivi.example.com`)

Variables d'environnement — RAG

Définies et validées dans apps/chatbot/src/config/rag_config.py:

Variable	Default	Min	Max	Description
`RAG_K_CHUNKS`	`5`	1	20	Nombre de chunks récupérés par FAISS
`RAG_N_EXAMPLES`	`4`	0	10	Nombre d'exemples Q&A few-shot
`RAG_QUERY_MODEL_ID`	`mistral-medium-latest`	—	—	Modèle LLM pour la génération
`RAG_EMBEDDING_MODEL_ID`	`mistral-embed`	—	—	Modèle pour les embeddings
`RAG_TEMP`	`0.2`	—	—	Température de génération
`RAG_BATCH_SIZE`	`64`	—	—	Taille des lots pour le calcul d'embeddings
`FEW_SHOTS_ENABLED`	`true`	—	—	Activer/désactiver les exemples few-shot

`validate_rag_parameters`

apps/chatbot/src/config/rag_config.py

def validate_rag_parameters(
    k: Optional[int] = None,
    n: Optional[int] = None,
    few_shots_enabled: Optional[bool] = None
) -> tuple[int, int, bool]:

Retourne des valeurs dans les limites définies. Si k ou n dépassent les limites, elles sont clampées. Si few_shots_enabled=False, n est forcé à 0.

Variables d'environnement — Orchestrateur

Définies dans apps/chatbot/src/config/orchestrator_config.py:

Variable	Default	Description
`ENABLE_ORCHESTRATOR`	`false`	Active le mode orchestrateur (classification d'intention)
`EXTERNAL_AGENT_URL`	—	URL de l'agent externe (ex: `http://agent-service:8080`)
`INTENT_DETECTION_PROMPT`	prompt interne	Prompt système pour la classification NORMAL/ALTER

Voir la page dédiée chatbot/orchestrator.mdx pour le fonctionnement complet.

Fonctions de configuration orchestrateur

is_orchestrator_enabled() -> bool
# Retourne True si ENABLE_ORCHESTRATOR == "true" (insensible à la casse)

get_external_agent_url() -> str
# Retourne EXTERNAL_AGENT_URL; lève ValueError si non défini et orchestrateur actif

get_intent_detection_prompt() -> str
# Retourne INTENT_DETECTION_PROMPT ou le prompt par défaut

get_enhanced_system_prompt(base_prompt: str) -> str
# Retourne base_prompt + instructions d'escalade si orchestrateur activé

Variables d'environnement — Index API (service secondaire)

Le service interfaces/api/index_api.py est un processus FastAPI séparé:

Variable	Default	Description
`INDEX_API_HOST`	`0.0.0.0`	Hôte du service Index API
`INDEX_API_PORT`	`8502`	Port du service Index API

Ce service est appelé depuis le serveur Bun via INDEX_API_URL (variable serveur).

Variables d'environnement — Chainlit & Branding

Variable	Description
`CHAINLIT_AUTH_SECRET`	Secret JWT pour les sessions Chainlit
`BOT_NAME`	Nom affiché dans l'interface Chainlit (injecté dans `.chainlit/config.toml` au démarrage Docker)
`CHAINLIT_PUBLIC_URL`	URL publique du chatbot (utilisée pour le lien d'icône dans le header Chainlit, ex: `http://localhost:8501`)
`OAUTH_AZURE_AD_CLIENT_ID`	Client ID Azure AD pour OAuth
`OAUTH_AZURE_AD_CLIENT_SECRET`	Client Secret Azure AD
`OAUTH_AZURE_AD_TENANT_ID`	Tenant ID Azure AD

Internationalisation (i18n)

Fichier: apps/chatbot/src/config/i18n.json
Chargé par config/i18n.py (TranslationManager).
En production: monté via ConfigMap Kubernetes.

{
  "defaultLanguage": "fr",
  "supportedLanguages": [
    { "code": "fr", "name": "Français" },
    { "code": "en", "name": "English" }
  ],
  "translations": {
    "error_message": {
      "fr": "Désolé, une erreur s'est produite.",
      "en": "Sorry, an error occurred."
    }
  }
}

TranslationManager.get_translation(key) retourne la traduction dans la langue courante ou le fallback anglais.

Exemple de `.env` complet (local)

# Obligatoire
MISTRAL_API_KEY=sk-xxxx
DATABASE_URL=postgresql://naivi:password@localhost:5432/naivi_db

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

# RAG
RAG_K_CHUNKS=5
RAG_N_EXAMPLES=4
RAG_QUERY_MODEL_ID=mistral-medium-latest
RAG_EMBEDDING_MODEL_ID=mistral-embed
RAG_TEMP=0.2
RAG_BATCH_SIZE=64

# Orchestrateur (optionnel)
ENABLE_ORCHESTRATOR=false
# EXTERNAL_AGENT_URL=http://external-agent:8080

# Auth Chainlit
CHAINLIT_AUTH_SECRET=changeme

Démarrage

# Interface Chainlit (port 8501 — aligné avec docker-compose)
cd apps/chatbot
chainlit run src/chatbot/interfaces/chainlit/app.py -w --port 8501

# Index API (service séparé, port 8502)
uvicorn src.chatbot.interfaces.api.index_api:app --host 0.0.0.0 --port 8502

Bonnes pratiques

Ne commitez jamais MISTRAL_API_KEY ni CHAINLIT_AUTH_SECRET.
Vérifiez que la DB contient des chunks category = 'dynamic' et des rôles initialisés avant de lancer.
En production: utilisez des Secrets Kubernetes pour les variables sensibles, des ConfigMaps pour i18n et les prompts.

Configuration

On this page