Assistant IA

Gerer une plateforme comme BeePass implique de jongler entre des dizaines de metriques, des centaines d'utilisateurs et des milliers de reines enregistrees. Plutot que de naviguer entre plusieurs pages pour trouver une information, l'assistant IA vous permet de poser vos questions en langage naturel --- comme si vous parliez a un collegue qui connait la plateforme sur le bout des doigts.

L'assistant est une console de conversation integree au backoffice. Il s'appuie sur Claude Sonnet (claude-sonnet-4-20250514) pour le raisonnement complexe avec boucle tool_use (la capacite de l'IA a utiliser des outils pour aller chercher des donnees), et Claude Haiku (claude-haiku-4-5-20251001) pour les brouillons de reponse support via RAG (Retrieval-Augmented Generation --- un systeme qui enrichit les reponses de l'IA avec des extraits de votre documentation).

Feature flag

L'assistant IA peut etre desactive via le feature flag ai_assistant dans Parametres > Systeme > Feature Flags. Quand desactive, la bulle flottante disparait et l'API retourne 403.

Architecture

Voici le parcours d'une question posee a l'assistant. Votre message transite par une API securisee qui verifie votre identite, rassemble le contexte pertinent depuis la base de donnees, puis envoie le tout a Claude en streaming (les mots apparaissent un par un, comme si l'IA tapait en temps reel).

                    ┌──────────────────────────────┐
                    │    Anthropic API (Claude)     │
                    │  api.anthropic.com/v1/messages│
                    │  Model: configurable          │
                    └──────────┬───────────────────┘
                               ▲ SSE stream
                               │
                    ┌──────────┴───────────────────┐
                    │  POST /api/admin/ai-assistant │
                    │  (Next.js Route Handler)      │
                    │  - verifyAdminFromRequest()   │
                    │  - fetchPlatformContext()     │
                    │  - buildSystemPrompt()        │
                    │  - SSE → text stream transform│
                    └──────────┬───────────────────┘
                               ▲ credentials: "include"
                               │ (HMAC admin cookie)
                               │
              ┌────────────────┴─────────────────┐
              │                                  │
    ┌─────────┴──────────┐         ┌─────────────┴────────────┐
    │ AdminAIAssistant   │         │ AdminAIChatBubble        │
    │ (page pleine)      │         │ (bulle flottante)        │
    │ /backoffice/       │         │ injectee dans layout.tsx  │
    │   ai-assistant     │         │ (toutes pages backoffice)│
    └────────────────────┘         └──────────────────────────┘

Flux de donnees

Voici en detail ce qui se passe entre le moment ou vous posez une question et le moment ou la reponse s'affiche :

L'admin pose une question (texte libre ou question rapide)
Le composant envoie POST /api/admin/ai-assistant avec l'historique de conversation
L'API verifie l'auth admin (cookie HMAC beepass-admin-token)
L'API analyse la question pour determiner le contexte DB necessaire (keywords matching)
L'API fetche les donnees pertinentes depuis Supabase (service_role, bypass RLS)
L'API construit le system prompt avec vocabulaire metier + contexte DB
L'API appelle Claude en streaming (SSE) avec les outils disponibles
La boucle tool_use s'execute (max rounds configurable, defaut 8)
Le composant lit le stream token par token et met a jour l'UI en temps reel
Le markdown est rendu via marked + DOMPurify (securise contre XSS)

Interface de conversation

L'assistant se presente sous deux formes complementaires, selon que vous souhaitez une conversation approfondie ou une reponse rapide sans quitter votre page actuelle.

Page pleine (`/backoffice/ai-assistant`)

Chat multi-tours avec retention de contexte. Chaque conversation conserve l'historique des echanges precedents pour permettre des questions de suivi sans avoir a reformuler le contexte. 6 questions rapides predefinies sont proposees.

Bulle flottante (toutes pages backoffice)

L'assistant IA est accessible depuis une bulle flottante positionnee en bas a droite de toutes les pages backoffice. Au clic, un panneau de chat (420x600px) s'ouvre en overlay. La conversation est preservee en sessionStorage --- naviguer entre les pages ne perd pas l'historique.

Un bouton "Ouvrir en pleine page" transfere la conversation vers /backoffice/ai-assistant (page dediee) via sessionStorage, permettant un espace de travail plus large.

Injecte dans le layout admin (layout.tsx), le panneau propose 4 questions rapides, un streaming identique a la page pleine, et un lien vers le mode plein ecran. Animation AnimatePresence spring (bulle) + fade/scale (panel).

Cas d'usage typiques

L'assistant est particulierement utile pour les taches qui necessiteraient autrement de naviguer entre plusieurs pages ou d'ecrire des requetes SQL :

Statut plateforme --- "Combien d'utilisateurs actifs ce mois-ci ?"
Investigation --- "Quels sont les derniers echecs de connexion pour cet email ?"
Support --- "Redige une reponse pour le ticket concernant un probleme d'import"
Securite --- "Lance un scan de securite et resume les findings critiques"
Diagnostic --- "Pourquoi le worker est-il marque unhealthy ?"
Genetique --- "Quelle est la distribution des races de reines F0 ?"

Questions rapides

Six questions predefinies sont proposees quand l'historique est vide, pour guider les administrateurs :

Question	Contexte charge
Resume des derniers tickets support	Peppermint API
Etat de sante du serveur	Beszel + Docker API
Statistiques des inscriptions recentes	Profiles DB
Analyse des erreurs API recentes	api_error_logs DB
Resume des derniers audits securite	Security findings DB
Etat des abonnements Stripe	Profiles + plans DB

Chaque question pre-charge le contexte necessaire avant d'envoyer la requete a Claude Sonnet, pour obtenir une reponse pertinente immediatement.

Outils disponibles (tool_use)

L'une des forces de l'assistant est sa capacite a aller chercher des informations par lui-meme. Quand vous posez une question dont la reponse necessite des donnees en base, l'assistant n'invente pas : il utilise des outils pour interroger la base de donnees, analyser les resultats, puis formuler une reponse basee sur des faits reels. Ce pattern tool_use (utilisation d'outils) lui permet d'appeler plusieurs outils par tour de conversation.

L'assistant dispose de 22 outils couvrant tous les aspects de la plateforme --- c'est le hub centralisateur de toutes les donnees admin :

Admin & Donnees (10 outils)

Outil	Description	Source
Statistiques admin	Utilisateurs, reines, evaluations, abonnements, erreurs 24h, tickets ouverts	Base de donnees (10 requetes paralleles)
Erreurs recentes	Dernieres erreurs API avec route, status code et message	Table `api_error_logs`
Recherche donnees	Recherche texte dans 8 tables : profiles, queens F0/F1, contacts, evaluations, cles API, findings securite, erreurs	Requetes ILIKE
Scan de securite	Declenchement d'un scan white hat parmi 19 outils (Shodan, Censys, ZAP, Nuclei, SSL Labs, Trivy, etc.)	APIs externes + Docker
Documentation admin	Charge la documentation detaillee d'une page admin parmi 19 pages disponibles	Fichiers Markdown
Recherche documentation	Recherche par mots-cles dans l'ensemble de la documentation admin (19 pages)	Index en memoire
Bilan financier	Revenus Stripe du mois, abonnes actifs, repartition plans, couts infrastructure, marge	Stripe API + base de donnees
Statistiques emails	Stats Brevo 30 jours : livraison, ouverture, clics, bounces, contacts bloques	Brevo API
Journal audit	Recherche dans le journal d'audit securite (18 types d'evenements, periode configurable)	Table `auth_audit_log`
Configuration site	Mode maintenance, seuils d'alerte, configuration IA des agents	Table `site_settings`

SEO (7 outils)

Outil	Description	Source
Module SEO	Execute un des 6 modules SEO (analyse semantique, plan article, redaction, FAQ, balises meta, audit page)	Claude API via `buildSeoPrompt()`
Scan SEO	Recupere les resultats du dernier scan SEO automatique (score, issues, recommandations)	Table `seo_reports`
Rapports SEO	Liste les derniers rapports SEO generes (module, mot-cle, tokens, date)	Table `seo_reports`
Analyse page SEO	Analyse SEO live d'une URL : title, meta, H1, canonical, OG, robots, score /100	Fetch direct + analyseur regex
Meta SEO config	Configuration meta SEO de toutes les pages publiques	Table `site_settings`
Sitemap config	Configuration sitemap.xml : URLs, frequences, priorites	Table `site_settings`
Robots.txt	Contenu robots.txt : routes autorisees et bloquees	Table `site_settings`

Infrastructure (3 outils)

Outil	Description	Source
Etat Docker	Containers : nom, etat (running/stopped/unhealthy), image, ports exposes	Docker Engine API (Unix socket)
Metriques serveur	CPU%, RAM, disque, uptime, load average, containers par consommation	Beszel PocketBase API (JWT cache 12min)
Etat Traefik	Routers, services, middlewares, trafic par code HTTP, connexions, certs TLS expiration	Traefik REST API + Prometheus metrics

Operations (2 outils)

Outil	Description	Source
Tickets support	Tickets Peppermint : titre, statut, priorite, date, resume par statut	Peppermint API (JWT cache)
Historique deploiements	20 derniers commits Git (type feat/fix/docs, message, date, stats)	Fichier `data/changelog.json`

Lecture seule par defaut

Les requetes base de donnees sont strictement en lecture seule. L'assistant ne peut pas modifier, inserer ou supprimer des donnees. Toute action modifiant l'etat de la plateforme necessite une confirmation explicite de l'administrateur.

Injection de contexte dynamique

A chaque question, le system prompt de l'assistant est enrichi automatiquement avec un contexte temps reel incluant : date et heure actuelles, nombre d'utilisateurs (eleveurs, testeurs), inscriptions 30 jours, abonnes actifs payants, reines F0/F1, evaluations, repartition abonnements, erreurs API 24h, findings securite ouverts, et le dernier score d'audit securite. Ce contexte est cache 60 secondes.

L'assistant decide ensuite de maniere autonome quels outils utiliser en fonction de votre question --- pas de keyword matching statique.

System prompt metier

Le system prompt (les instructions de base donnees a l'IA qui definissent son role et son comportement) est configurable dynamiquement via /backoffice/ai-config onglet Assistant IA. Le template utilise le placeholder {{adminContext}} qui est remplace au runtime par les donnees temps reel.

Le prompt par defaut (optimise v2.0 ~3900 tokens) inclut :

Role : expert BeePass + expert securite white hat
Architecture : stack technique, infrastructure, auth, emails, paiements
Resume : les 30 pages admin organisees par section (sans detail --- renvoi vers les outils de documentation)
Instructions outils : quand utiliser chacun des 22 outils
Regles : repondre en francais, precis, combiner outils, ne jamais inventer

Pattern tool_use

Pour mieux comprendre comment l'assistant raisonne, voici un exemple concret. L'IA ne repond pas directement : elle decompose la question, utilise un outil pour obtenir les donnees, puis formule une reponse basee sur le resultat reel.

Administrateur : "Combien de reines ont ete importees cette semaine ?"
   ▼
Assistant → tool_use: requete DB (SELECT count(*) FROM queens_f0 WHERE created_at > ...)
   ▼
Resultat : 47
   ▼
Assistant : "47 reines F0 ont ete importees cette semaine, dont 12 aujourd'hui."

Protections contre les boucles

Pour eviter qu'une sequence d'appels d'outils ne tourne indefiniment (par exemple si un outil renvoie des resultats ambigus qui poussent l'IA a re-interroger en boucle), plusieurs garde-fous sont en place :

Protection	Description	Defaut
Tool rounds max	Nombre maximum d'iterations tool_use par reponse	8 rounds
Loop timeout	Duree maximale avant interruption forcee d'une boucle d'outils	300 secondes
AbortController	Timeout HTTP sur l'appel Anthropic	120 secondes
Rate limit retry	Retry automatique sur 429 Anthropic avec backoff exponentiel	2 retries (10s, 20s)
Review obligatoire	Toutes les reponses de l'IA sont presentees a l'administrateur avant toute action	Toujours actif

Revue systematique

L'assistant ne prend jamais d'action autonome. Chaque reponse est affichee pour validation par l'administrateur. Les suggestions d'actions (envoi d'email, modification de role, etc.) necessitent une confirmation manuelle.

Modeles utilises

BeePass utilise trois modeles d'IA differents, chacun optimise pour un usage precis --- comme on utiliserait des outils differents selon la tache : un marteau pour les clous, un tournevis pour les vis.

Modele	ID	Usage	Caracteristiques
Claude Sonnet	`claude-sonnet-4-20250514`	Assistant IA admin --- raisonnement complexe, tool_use, investigation	Contexte long, raisonnement multi-etapes, outils
Claude Haiku	`claude-haiku-4-5-20251001`	Brouillons support RAG --- reponses rapides basees sur la documentation	Rapide (1-3s), economique, ideal pour le RAG
Llama 3.2 3B	Via Ollama	Embeddings RAG + suggestions import IA	Local, pas d'appel API externe

La selection du modele et ses parametres (temperature, max tokens, system prompt) sont configurables dans la page Configuration IA.

Configuration dynamique

Tous les parametres de l'assistant sont modifiables a chaud (sans redemarrage ni redeploiement) depuis site_settings.ai_agents_config.assistant via loadAgentConfig('assistant') :

Parametre	Defaut	Configurable via
Modele	`claude-sonnet-4-20250514`	Configuration IA onglet Assistant
Temperature	0.3	Slider 0.0 -- 1.0
Max tokens	4096	Champ numerique
Tool rounds max	8	Champ numerique
Loop timeout	300s	Champ numerique
System prompt	Template metier apicole + `{{adminContext}}`	Textarea monospace

Le cache configuration a un TTL de 5 minutes avec invalidation immediate a la sauvegarde.

API route

POST /api/admin/ai-assistant

Champ	Valeur
Auth	Cookie HMAC `beepass-admin-token` via `verifyAdminFromRequest()`
Request body	`{ messages: [{ role: "user"\|"assistant", content: string }] }`
Response	`text/plain; charset=utf-8` stream (pas JSON)
Error responses	`{ error: "Unauthorized" }` (401), `{ error: "Forbidden" }` (403), `{ error: "not_configured" }` (200), `{ error: "Rate limit Anthropic — réessayez dans 1 minute" }` (429), `{ error: "AI assistant error" }` (500)
Rate limit retry	`fetchWithRetry()` : retry auto sur 429 Anthropic (2 retries, backoff 10s/20s, cap 60s, respect header `retry-after`)
Error logging	`logApiError()` fire-and-forget

Variable d'environnement requise

Variable	Usage
`ANTHROPIC_API_KEY`	Cle API Anthropic (sk-ant-...). Si vide, la route retourne `not_configured`

Securite

L'assistant manipule des donnees sensibles (profils utilisateurs, logs de securite, statistiques). Plusieurs couches de protection garantissent que seuls les administrateurs authentifies y accedent, et que les reponses affichees ne contiennent pas de code malveillant.

Point	Detail
Auth	Cookie HMAC via `verifyAdminFromRequest()`
API key	`ANTHROPIC_API_KEY` server-side only, jamais exposee cote client
XSS	`DOMPurify.sanitize()` sur tout le markdown rendu
Streaming	SSE Anthropic transforme en text stream pur (pas de JSON brut cote client)
Contexte DB	service_role key (bypass RLS) --- donnees admin-only
Error logging	`logApiError()` fire-and-forget dans `api_error_logs`

Fichiers sources

Fichier	Description
`src/app/api/admin/ai-assistant/route.ts`	API route streaming Claude tool_use + contexte DB (~280 lignes)
`src/app/components/admin/AdminAIAssistant.tsx`	Page chat pleine (~290 lignes)
`src/app/components/admin/AdminAIChatBubble.tsx`	Bulle flottante (~310 lignes)
`src/app/(DashboardAdmin)/backoffice/ai-assistant/page.tsx`	Page wrapper
`src/lib/ai-config.ts`	Module unifie : types, defaults, cache 5min, loader par agent

Architecture​

Flux de donnees​

Interface de conversation​

Page pleine (/backoffice/ai-assistant)​

Bulle flottante (toutes pages backoffice)​

Cas d'usage typiques​

Questions rapides​

Outils disponibles (tool_use)​

Admin & Donnees (10 outils)​

SEO (7 outils)​

Infrastructure (3 outils)​

Operations (2 outils)​

Injection de contexte dynamique​

System prompt metier​

Pattern tool_use​

Protections contre les boucles​

Modeles utilises​

Configuration dynamique​

API route​

POST /api/admin/ai-assistant​

Variable d'environnement requise​

Securite​

Fichiers sources​