feat(agentic-week1): conversational memory, RAG threshold, wallet alerts, weekly reports, campaign scheduling

- AIAgentHandler: Redis sliding window (20 entries, TTL 24h) for conversation
history injected into system prompt — AI_AGENT now remembers context
- IndexingService.searchRelevantContext: cosine threshold 0.70 — returns '' if
no chunk is relevant so agent responds honestly instead of hallucinating
- add-hnsw-index.ts: one-shot HNSW index script (m=16, ef=64) for ~10x faster
pgvector cosine search on large knowledge bases
- scheduler.ts: hourly wallet alert (email via Brevo if < 3 days runway,
6h Redis suppression) + weekly report every Monday 07:00 UTC with trend vs
previous week and color-coded wallet status
- queue.ts + campaigns.ts: sendAt ISO-8601 parameter on broadcast/campaign
routes — BullMQ delay option schedules jobs natively, no cron needed
- docs/agentic/: roadmap updated with Semaine 1 marked complete

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

apps/api/src/routes/campaigns.ts

@@ -29,23 +29,34 @@ export default async function campaignRoutes(fastify: FastifyInstance) {
         }
     });
 
-    // Send Campaign to Broadcast List
+    // Send Campaign to Broadcast List (with optional sendAt scheduling)
     fastify.post('/:id/campaigns/send', async (req, reply) => {
+        const schema = z.object({
+            listId: z.string().uuid(),
+            message: z.string().min(1),
+            sendAt: z.string().datetime({ offset: true }).optional(),
+        });
+        const parsed = schema.safeParse(req.body);
+        if (!parsed.success) return reply.code(400).send({ error: parsed.error.flatten() });
+
         const { id: organizationId } = req.params as { id: string };
-        const { listId, message } = req.body as { listId: string, message: string };
+        const { listId, message, sendAt } = parsed.data;
 
-        if (!listId || !message) {
-            return reply.code(400).send({ error: 'listId and message are required' });
+        if (sendAt && new Date(sendAt) <= new Date()) {
+            return reply.code(400).send({ error: 'sendAt must be in the future' });
         }
 
         try {
             const { scheduleBroadcast } = await import('../services/queue');
-            await scheduleBroadcast({ organizationId, listId, message });
+            await scheduleBroadcast({ organizationId, listId, message, sendAt });
 
-            return reply.code(202).send({ 
-                ok: true, 
-                status: 'queued', 
-                message: 'Campagne en cours d\'envoi en arrière-plan' 
+            return reply.code(202).send({
+                ok: true,
+                status: sendAt ? 'scheduled' : 'queued',
+                scheduledFor: sendAt ?? null,
+                message: sendAt
+                    ? `Campagne programmée pour le ${new Date(sendAt).toLocaleString('fr-FR')}`
+                    : "Campagne en cours d'envoi en arrière-plan",
             });
         } catch (err) {
             fastify.log.error(err);
@@ -74,34 +85,46 @@ export default async function campaignRoutes(fastify: FastifyInstance) {
         }
     });
 
-    // New Broadcast Campaign Route
+    // New Broadcast Campaign Route (with optional sendAt scheduling)
     fastify.post('/:id/campaigns/broadcast', async (req, reply) => {
+        const schema = z.object({
+            message: z.string().optional(),
+            listId: z.string().uuid().optional(),
+            templateName: z.string().optional(),
+            templateLanguage: z.string().optional(),
+            sendAt: z.string().datetime({ offset: true }).optional(),
+        });
+        const parsed = schema.safeParse(req.body);
+        if (!parsed.success) return reply.code(400).send({ error: parsed.error.flatten() });
+
         const { id: organizationId } = req.params as { id: string };
-        const { message, listId, templateName, templateLanguage } = req.body as { 
-            message: string, 
-            listId?: string,
-            templateName?: string,
-            templateLanguage?: string
-        };
+        const { message, listId, templateName, templateLanguage, sendAt } = parsed.data;
 
         if (!message && !templateName) {
             return reply.code(400).send({ error: 'Message content or templateName is required' });
         }
+        if (sendAt && new Date(sendAt) <= new Date()) {
+            return reply.code(400).send({ error: 'sendAt must be in the future' });
+        }
 
         try {
             const { scheduleCampaign } = await import('../services/queue');
-            await scheduleCampaign({ 
-                organizationId, 
-                messageContent: message, 
+            await scheduleCampaign({
+                organizationId,
+                messageContent: message ?? '',
                 listId,
                 templateName,
-                templateLanguage
+                templateLanguage,
+                sendAt,
             });
 
             return {
                 ok: true,
-                status: 'queued',
-                message: 'Votre campagne a été mise en file d\'attente pour une diffusion progressive.'
+                status: sendAt ? 'scheduled' : 'queued',
+                scheduledFor: sendAt ?? null,
+                message: sendAt
+                    ? `Campagne programmée pour le ${new Date(sendAt).toLocaleString('fr-FR')}`
+                    : "Votre campagne a été mise en file d'attente pour une diffusion progressive.",
             };
         } catch (err) {
             fastify.log.error(err);

apps/api/src/services/queue.ts

@@ -113,25 +113,37 @@ export async function scheduleInboundMessage(payload: { phone: string, text: str
     });
 }
 
-/** 📢 BROADCAST: Enqueue a mass message task. */
-export async function scheduleBroadcast(payload: { organizationId: string, listId: string, message: string }) {
-    await whatsappQueue.add('send-broadcast', payload, {
-        attempts: 1, // We handle retry logic within the loop if needed, but the whole job shouldn't necessarily retry
-        removeOnComplete: true
+/** 📢 BROADCAST: Enqueue a mass message task with optional future scheduling. */
+export async function scheduleBroadcast(payload: {
+    organizationId: string;
+    listId: string;
+    message: string;
+    sendAt?: string; // ISO 8601 — if set, job is delayed until this time
+}) {
+    const { sendAt, ...data } = payload;
+    const delayMs = sendAt ? Math.max(0, new Date(sendAt).getTime() - Date.now()) : 0;
+    await whatsappQueue.add('send-broadcast', data, {
+        attempts: 1,
+        removeOnComplete: true,
+        ...(delayMs > 0 ? { delay: delayMs } : {}),
     });
 }
 
-/** 🚀 CAMPAIGN: Enqueue a mass campaign task for all contacts or a specific list. */
-export async function scheduleCampaign(payload: { 
-    organizationId: string, 
-    messageContent: string, 
-    listId?: string,
-    templateName?: string,
-    templateLanguage?: string
+/** 🚀 CAMPAIGN: Enqueue a mass campaign task with optional future scheduling. */
+export async function scheduleCampaign(payload: {
+    organizationId: string;
+    messageContent: string;
+    listId?: string;
+    templateName?: string;
+    templateLanguage?: string;
+    sendAt?: string; // ISO 8601 — if set, job is delayed until this time
 }) {
-    await whatsappQueue.add('process-campaign', payload, {
+    const { sendAt, ...data } = payload;
+    const delayMs = sendAt ? Math.max(0, new Date(sendAt).getTime() - Date.now()) : 0;
+    await whatsappQueue.add('process-campaign', data, {
         attempts: 1,
-        removeOnComplete: true
+        removeOnComplete: true,
+        ...(delayMs > 0 ? { delay: delayMs } : {}),
     });
 }
 

apps/whatsapp-worker/src/handlers/AIAgentHandler.ts

@@ -1,56 +1,94 @@
 import { MessageContext, MessageHandler } from './types';
 import { logger } from '../logger';
 import { AIPedagogyService } from '../services/ai-pedagogy';
+import { redis } from '../lib/redis';
+
+const CONV_HISTORY_LIMIT = 20;  // Max entries in Redis list (10 exchanges)
+const CONV_TTL_SECONDS   = 86_400; // 24h TTL — conversation expires after inactivity
+
+interface ConvMessage { role: 'user' | 'assistant'; content: string }
+
+async function loadHistory(key: string): Promise<ConvMessage[]> {
+    try {
+        const raw = await redis.lrange(key, 0, CONV_HISTORY_LIMIT - 1);
+        return raw.reverse().map(r => JSON.parse(r) as ConvMessage);
+    } catch {
+        return [];
+    }
+}
+
+async function saveHistory(key: string, user: string, assistant: string): Promise<void> {
+    try {
+        const userEntry      = JSON.stringify({ role: 'user',      content: user });
+        const assistantEntry = JSON.stringify({ role: 'assistant', content: assistant });
+        await redis.lpush(key, assistantEntry, userEntry);
+        await redis.ltrim(key, 0, CONV_HISTORY_LIMIT - 1);
+        await redis.expire(key, CONV_TTL_SECONDS);
+    } catch (err) {
+        logger.warn({ err }, '[AIAgent] Failed to persist conversation history');
+    }
+}
 
 export class AIAgentHandler implements MessageHandler {
     async canHandle(ctx: MessageContext): Promise<boolean> {
-        // Only handle if the organization mode is explicitly AI_AGENT
         return ctx.organization?.mode === 'AI_AGENT';
     }
 
     async handle(ctx: MessageContext): Promise<boolean> {
         const { phone, text, organization, whatsappQueue, traceId } = ctx;
-
         if (!organization) return false;
 
         logger.info(`${traceId} Processing via AIAgentHandler for Org: ${organization.id}`);
 
         try {
-            // 1. Prepare the system prompt
-            const userLang = ctx.user?.language || 'FR';
-            let systemPrompt = organization.customPrompt || "Tu es un assistant virtuel utile et poli.";
+            const userLang   = ctx.user?.language || 'FR';
+            const userId     = ctx.user?.id ?? phone;
+            const historyKey = `conv:${userId}:${organization.id}`;
+
+            // 1. Prepare system prompt
+            let systemPrompt = organization.customPrompt || 'Tu es un assistant virtuel utile et poli.';
             systemPrompt += `\n\nIMPORTANT: Réponds TOUJOURS en langue: ${userLang}.`;
-            
-            // 2. RAG / Knowledge Base logic
+
+            // 2. Load conversation history and inject as context
+            const history = await loadHistory(historyKey);
+            if (history.length > 0) {
+                const historyText = history
+                    .map(m => `${m.role === 'user' ? 'Client' : 'Toi'}: ${m.content}`)
+                    .join('\n');
+                systemPrompt += `\n\nHISTORIQUE DE LA CONVERSATION (du plus ancien au plus récent):\n${historyText}\n\nContinue la conversation de façon cohérente avec cet historique.`;
+            }
+
+            // 3. RAG — Knowledge Base context (filtered by relevance threshold)
             if (organization.knowledgeBaseUrl) {
                 const { IndexingService } = await import('../services/indexing');
                 const context = await IndexingService.searchRelevantContext(organization.id, text);
-                
                 if (context) {
-                    systemPrompt += `\n\nCONTEXTE RELEVANT DE LA BASE DE CONNAISSANCES:\n${context}\n\nUtilise uniquement ce contexte pour répondre si la question concerne les produits ou services de l'entreprise.`;
+                    systemPrompt += `\n\nCONTEXTE DE LA BASE DE CONNAISSANCES:\n${context}\n\nUtilise ce contexte pour répondre si la question concerne les produits ou services de l'entreprise.`;
                 }
             }
 
-            // 3. Generate response via API
+            // 4. Generate response
             const responseText = await AIPedagogyService.generateChat(systemPrompt, text, organization.id);
 
-            // 4. Send response back to user
+            // 5. Persist exchange to Redis history (fire-and-forget)
+            saveHistory(historyKey, text, responseText);
+
+            // 6. Send response
             await whatsappQueue.add('send-message-direct', {
                 phone,
                 text: responseText,
-                organizationId: organization.id
+                organizationId: organization.id,
             });
 
             return true;
-
         } catch (error) {
             logger.error(`${traceId} AIAgentHandler failed: ${error}`);
             await whatsappQueue.add('send-message-direct', {
                 phone,
-                text: "Désolé, je rencontre une difficulté technique. Veuillez réessayer plus tard.",
-                organizationId: organization.id
+                text: 'Désolé, je rencontre une difficulté technique. Veuillez réessayer plus tard.',
+                organizationId: organization.id,
             });
-            return true; // We handled the error, stop propagation
+            return true;
         }
     }
 }

apps/whatsapp-worker/src/index.ts

@@ -257,9 +257,11 @@ const start = async () => {
         logger.info(`🚀 WhatsApp Worker + Bridge listening on port ${PORT}`);
         
         // Start the daily cron scheduler + token expiry monitor
-        const { startDailyScheduler, startTokenExpiryMonitor } = await import('./scheduler');
+        const { startDailyScheduler, startTokenExpiryMonitor, startWalletAlertMonitor, startWeeklyReportScheduler } = await import('./scheduler');
         startDailyScheduler();
         startTokenExpiryMonitor();
+        startWalletAlertMonitor();
+        startWeeklyReportScheduler();
     } catch (err) {
         logger.error('Failed to start worker server:', err);
         process.exit(1);

apps/whatsapp-worker/src/scheduler.ts

@@ -2,6 +2,7 @@ import { logger } from './logger';
 import cron from 'node-cron';
 import { prisma } from './services/prisma';
 import { whatsappQueue } from './lib/queues';
+import { EmailService } from './services/email';
 
 export function startDailyScheduler() {
     // Runs at 08:00 AM every day (Dakar time = UTC+0 in winter, so 8 UTC = 8 Dakar)
@@ -120,3 +121,177 @@ export function startTokenExpiryMonitor() {
 
     logger.info('[TOKEN-MONITOR] Meta token expiry monitor initialized (cron: every Monday 09:00 UTC).');
 }
+
+// ─── Wallet Alert Monitor ────────────────────────────────────────────────────
+// Runs every hour. Emails the org admin if wallet < 3 days of runway left.
+
+async function findOrgAdminEmail(organizationId: string): Promise<{ email: string; name: string } | null> {
+    const admin = await prisma.user.findFirst({
+        where: { organizationId, role: { in: ['ORG_ADMIN', 'ADMIN'] }, email: { not: null } },
+        select: { email: true, name: true },
+    });
+    return admin ? { email: admin.email!, name: admin.name ?? 'Administrateur' } : null;
+}
+
+export function startWalletAlertMonitor() {
+    cron.schedule('0 * * * *', async () => {
+        logger.info('[WALLET-MONITOR] Running hourly wallet check...');
+        try {
+            const now = new Date();
+            const weekAgo = new Date(now.getTime() - 7 * 86_400_000);
+
+            const orgsAtRisk = await prisma.organization.findMany({
+                where: { walletBalance: { lte: 500 }, isHardStopped: false, subscriptionStatus: 'ACTIVE' },
+                select: { id: true, name: true, walletBalance: true },
+            });
+
+            for (const org of orgsAtRisk) {
+                // Calculate 7-day burn rate
+                const debits = await prisma.walletTransaction.aggregate({
+                    where: { organizationId: org.id, amount: { lt: 0 }, createdAt: { gte: weekAgo } },
+                    _sum: { amount: true },
+                });
+                const weeklyDebit = Math.abs(debits._sum.amount ?? 0);
+                const dailyBurn   = weeklyDebit / 7;
+                const daysLeft    = dailyBurn > 0 ? org.walletBalance / dailyBurn : null;
+
+                // Only alert if < 3 days of runway (and we have a burn rate)
+                if (daysLeft === null || daysLeft > 3) continue;
+
+                const admin = await findOrgAdminEmail(org.id);
+                if (!admin) continue;
+
+                const alertKey = `wallet:alert:${org.id}`;
+                // Avoid re-alerting within 6 hours for same org
+                const { redis } = await import('./lib/redis');
+                const alreadyAlerted = await redis.get(alertKey);
+                if (alreadyAlerted) continue;
+
+                logger.warn({ organizationId: org.id, daysLeft: daysLeft.toFixed(1) }, '[WALLET-MONITOR] Sending low-wallet alert');
+                await EmailService.sendEmail({
+                    to: admin.email,
+                    subject: `⚠️ Solde faible — ${org.name} (${Math.round(daysLeft)} jour(s) restant${daysLeft < 1 ? ' — SERVICE EN DANGER' : ''})`,
+                    htmlContent: `
+                        <div style="font-family:sans-serif;max-width:600px;margin:auto;padding:20px;border:1px solid #eee;border-radius:10px;">
+                            <h2 style="color:${daysLeft < 1 ? '#dc2626' : '#d97706'};">
+                                ${daysLeft < 1 ? '🚨 Service en danger' : '⚠️ Solde faible'} — ${org.name}
+                            </h2>
+                            <p>Bonjour ${admin.name},</p>
+                            <p>À votre rythme de consommation actuel (<strong>${Math.round(dailyBurn)} crédits/jour</strong>),
+                            il reste environ <strong>${daysLeft < 1 ? 'moins d\'1 jour' : `${Math.round(daysLeft)} jour(s)`}</strong>
+                            avant que le service soit suspendu.</p>
+                            <div style="background:#fef3c7;border:1px solid #fbbf24;border-radius:8px;padding:16px;margin:20px 0;">
+                                <p style="margin:0;font-size:1.25rem;font-weight:bold;">Solde actuel : ${org.walletBalance} crédits (= ${org.walletBalance * 10} FCFA)</p>
+                            </div>
+                            <p>Rechargez votre wallet pour éviter toute interruption de service.</p>
+                            <a href="https://admin.xamle.studio/billing" style="display:inline-block;padding:12px 24px;background:#059669;color:white;text-decoration:none;border-radius:8px;font-weight:bold;">Recharger mon wallet</a>
+                            <p style="color:#64748b;font-size:0.875rem;margin-top:40px;">L'équipe Xamlé Studio</p>
+                        </div>`,
+                }).catch(e => logger.error({ e }, '[WALLET-MONITOR] Alert email failed'));
+
+                await redis.set(alertKey, '1', 'EX', 6 * 3600); // Suppress for 6h
+            }
+        } catch (err) {
+            logger.error({ err }, '[WALLET-MONITOR] Hourly check failed');
+        }
+    });
+
+    logger.info('[WALLET-MONITOR] Hourly wallet alert monitor initialized.');
+}
+
+// ─── Weekly Report ───────────────────────────────────────────────────────────
+// Runs every Monday at 07:00 UTC. Sends a usage summary to each org admin.
+
+const FEATURE_LABELS: Record<string, string> = {
+    LESSON: 'Leçons', FEEDBACK: 'Feedbacks', DEEPDIVE: 'Approfondissements',
+    TRANSCRIPTION: 'Transcriptions audio', IMAGE_ANALYSIS: 'Analyses image',
+    CAMPAIGN: 'Campagnes', ONBOARDING: 'Onboarding', OTHER: 'Autres',
+};
+
+export function startWeeklyReportScheduler() {
+    cron.schedule('0 7 * * 1', async () => {
+        logger.info('[WEEKLY-REPORT] Generating weekly reports...');
+        try {
+            const weekAgo = new Date(Date.now() - 7 * 86_400_000);
+            const prevWeekAgo = new Date(Date.now() - 14 * 86_400_000);
+
+            const orgs = await prisma.organization.findMany({
+                where: { subscriptionStatus: 'ACTIVE' },
+                select: { id: true, name: true, walletBalance: true, whatsappMessagesSent: true, aiCreditsUsed: true, aiCreditsLimit: true },
+            });
+
+            for (const org of orgs) {
+                const admin = await findOrgAdminEmail(org.id);
+                if (!admin) continue;
+
+                const [thisWeek, prevWeek, breakdown] = await Promise.all([
+                    prisma.usageEvent.aggregate({
+                        where: { organizationId: org.id, createdAt: { gte: weekAgo }, type: { not: 'WHATSAPP_SENT' } },
+                        _sum: { costUsd: true }, _count: { id: true },
+                    }),
+                    prisma.usageEvent.aggregate({
+                        where: { organizationId: org.id, createdAt: { gte: prevWeekAgo, lt: weekAgo }, type: { not: 'WHATSAPP_SENT' } },
+                        _count: { id: true },
+                    }),
+                    prisma.usageEvent.groupBy({
+                        by: ['feature'],
+                        where: { organizationId: org.id, createdAt: { gte: weekAgo }, type: { not: 'WHATSAPP_SENT' } },
+                        _count: { id: true },
+                        orderBy: { _count: { id: 'desc' } },
+                        take: 1,
+                    }),
+                ]);
+
+                const calls     = thisWeek._count.id;
+                const prevCalls = prevWeek._count.id;
+                const costFcfa  = Math.round((thisWeek._sum.costUsd ?? 0) * 600);
+                const topFeat   = FEATURE_LABELS[breakdown[0]?.feature ?? ''] ?? 'N/A';
+                const trend     = prevCalls > 0 ? Math.round(((calls - prevCalls) / prevCalls) * 100) : 0;
+                const trendStr  = trend >= 0 ? `+${trend}%` : `${trend}%`;
+                const trendColor = trend >= 0 ? '#059669' : '#dc2626';
+
+                if (calls === 0 && org.walletBalance > 500) continue; // Skip inactive orgs with healthy balance
+
+                await EmailService.sendEmail({
+                    to: admin.email,
+                    subject: `📊 Rapport hebdomadaire Xamlé — ${org.name}`,
+                    htmlContent: `
+                        <div style="font-family:sans-serif;max-width:600px;margin:auto;padding:20px;border:1px solid #eee;border-radius:10px;">
+                            <h2 style="color:#1e293b;">📊 Rapport hebdomadaire — ${org.name}</h2>
+                            <p>Bonjour ${admin.name}, voici votre résumé de la semaine écoulée.</p>
+                            <table style="width:100%;border-collapse:collapse;margin:20px 0;">
+                                <tr style="background:#f8fafc;">
+                                    <td style="padding:10px;border:1px solid #e2e8f0;">Appels IA cette semaine</td>
+                                    <td style="padding:10px;border:1px solid #e2e8f0;font-weight:bold;">${calls.toLocaleString('fr-FR')} <span style="color:${trendColor};font-size:0.875rem;">(${trendStr} vs sem. précédente)</span></td>
+                                </tr>
+                                <tr>
+                                    <td style="padding:10px;border:1px solid #e2e8f0;">Coût IA</td>
+                                    <td style="padding:10px;border:1px solid #e2e8f0;font-weight:bold;">${costFcfa.toLocaleString('fr-FR')} FCFA</td>
+                                </tr>
+                                <tr style="background:#f8fafc;">
+                                    <td style="padding:10px;border:1px solid #e2e8f0;">Fonctionnalité principale</td>
+                                    <td style="padding:10px;border:1px solid #e2e8f0;font-weight:bold;">${topFeat}</td>
+                                </tr>
+                                <tr>
+                                    <td style="padding:10px;border:1px solid #e2e8f0;">Solde wallet</td>
+                                    <td style="padding:10px;border:1px solid #e2e8f0;font-weight:bold;color:${org.walletBalance < 200 ? '#dc2626' : '#059669'};">${org.walletBalance} crédits (${org.walletBalance * 10} FCFA)</td>
+                                </tr>
+                                <tr style="background:#f8fafc;">
+                                    <td style="padding:10px;border:1px solid #e2e8f0;">Crédits IA (mois en cours)</td>
+                                    <td style="padding:10px;border:1px solid #e2e8f0;font-weight:bold;">${org.aiCreditsUsed} / ${org.aiCreditsLimit}</td>
+                                </tr>
+                            </table>
+                            <a href="https://admin.xamle.studio/analytics" style="display:inline-block;padding:12px 24px;background:#4f46e5;color:white;text-decoration:none;border-radius:8px;font-weight:bold;">Voir le détail complet</a>
+                            <p style="color:#64748b;font-size:0.875rem;margin-top:40px;">L'équipe Xamlé Studio</p>
+                        </div>`,
+                }).catch(e => logger.error({ e, orgId: org.id }, '[WEEKLY-REPORT] Email failed'));
+            }
+
+            logger.info('[WEEKLY-REPORT] Weekly reports sent.');
+        } catch (err) {
+            logger.error({ err }, '[WEEKLY-REPORT] Failed');
+        }
+    });
+
+    logger.info('[WEEKLY-REPORT] Weekly report scheduler initialized (cron: every Monday 07:00 UTC).');
+}

apps/whatsapp-worker/src/services/indexing.ts

@@ -198,27 +198,41 @@ export class IndexingService {
     }
 
     /**
-     * Searches for relevant chunks based on a query string.
+     * Searches for relevant chunks using cosine similarity with a minimum relevance threshold.
+     * Returns empty string if no chunk exceeds the threshold — the agent will then respond
+     * honestly that it doesn't have specific information on the topic.
      */
-    static async searchRelevantContext(organizationId: string, query: string, limit: number = 3): Promise<string> {
+    static async searchRelevantContext(
+        organizationId: string,
+        query: string,
+        limit: number = 3,
+        threshold: number = 0.70
+    ): Promise<string> {
         try {
             const queryEmbedding = await this.generateEmbedding(query);
             // Prisma.raw is safe here: embedding is machine-generated floats from OpenAI, not user input
             const vecRaw = Prisma.raw(`'[${queryEmbedding.join(',')}]'::vector`);
 
-            // Cosine similarity search using pgvector
-            const results: any[] = await prisma.$queryRaw(Prisma.sql`
-                SELECT content, 1 - (embedding <=> ${vecRaw}) as similarity
+            // Cosine similarity search via HNSW index (if created) — threshold filters irrelevant chunks
+            const results: Array<{ content: string; similarity: number }> = await prisma.$queryRaw(Prisma.sql`
+                SELECT content, 1 - (embedding <=> ${vecRaw}) AS similarity
                 FROM "KnowledgeBaseEntry"
                 WHERE "organizationId" = ${organizationId}
+                  AND 1 - (embedding <=> ${vecRaw}) > ${threshold}
                 ORDER BY embedding <=> ${vecRaw}
                 LIMIT ${limit}
             `);
 
+            if (results.length === 0) {
+                logger.debug(`[RETRIEVAL] No chunks above threshold ${threshold} for org ${organizationId}`);
+                return '';
+            }
+
+            logger.debug(`[RETRIEVAL] Found ${results.length} relevant chunks (best: ${results[0]?.similarity?.toFixed(3)})`);
             return results.map(r => r.content).join('\n\n---\n\n');
         } catch (error) {
             logger.error(`[RETRIEVAL] Search failed: ${error}`);
-            return "";
+            return '';
         }
     }
 }

docs/agentic/audit_agentic_complet_2026.md

@@ -0,0 +1,1339 @@
+# Audit Complet Xamlé — Fonctionnalités, IA Agentique & Avancées Technologiques
+
+> **Date :** 13 mai 2026  
+> **Scope :** Audit exhaustif de toute la plateforme (frontend, backend, worker, IA, database, UX/UI) + roadmap agentique complète  
+> **Objectif :** Cartographier tout ce qui existe, identifier tout ce qui peut être automatisé, et exploiter les dernières avancées technologiques disponibles aujourd'hui
+
+---
+
+## Table des matières
+
+1. [Vue d'ensemble de la plateforme](#1-vue-densemble)
+2. [Inventaire complet — Base de données](#2-base-de-données)
+3. [Inventaire complet — Backend (API Fastify)](#3-backend-api-fastify)
+4. [Inventaire complet — Worker BullMQ](#4-worker-bullmq)
+5. [Inventaire complet — SDK IA](#5-sdk-ia)
+6. [Inventaire complet — Frontend Admin](#6-frontend-admin)
+7. [Inventaire complet — Prompts & Templates IA](#7-prompts--templates-ia)
+8. [Tarification & Wallet](#8-tarification--wallet)
+9. [Lacunes & dette technique identifiées](#9-lacunes--dette-technique)
+10. [Roadmap IA Agentique — tout ce qui peut être automatisé](#10-roadmap-ia-agentique)
+11. [Dernières avancées technologiques applicables](#11-dernières-avancées-technologiques)
+12. [Matrice de priorisation](#12-matrice-de-priorisation)
+
+---
+
+## 1. Vue d'ensemble
+
+### Qu'est-ce que Xamlé ?
+
+Xamlé est une **plateforme SaaS multi-tenant d'automatisation WhatsApp Business** destinée aux entreprises et organisations africaines. Elle permet de gérer la relation client, la formation, et le support via WhatsApp en combinant IA générative, workflows métier et facturation à la consommation.
+
+### Architecture globale
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  Meta WhatsApp Business API                                       │
+└─────────────────────────┬────────────────────────────────────────┘
+                          │ Webhook POST
+                          ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  apps/api  (Fastify v4 — port 3000)                              │
+│  • Répond 200 OK < 100ms (règle absolue)                         │
+│  • Vérifie X-Hub-Signature-256                                    │
+│  • Enfile le job dans BullMQ via bridge localhost:8082            │
+└─────────────────────────┬────────────────────────────────────────┘
+                          │ HTTP → BullMQ
+                          ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  apps/whatsapp-worker  (BullMQ consumer)                          │
+│  • Handlers en chaîne : AIAgent → Onboarding → Command →         │
+│    Navigation → Exercise                                          │
+│  • Toute la logique métier ici                                    │
+└──────────┬─────────────────────────────────┬────────────────────┘
+           │                                 │
+           ▼                                 ▼
+┌──────────────────────┐       ┌─────────────────────────────────┐
+│  packages/database   │       │  packages/ai-sdk                │
+│  (Prisma + pgvector) │       │  OpenAI / Gemini / BYOK         │
+│  Neon PostgreSQL     │       │  Whisper STT / DALL-E / TTS     │
+└──────────────────────┘       └─────────────────────────────────┘
+           │
+           ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  apps/admin  (React/Vite — port 5173)                            │
+│  Dashboard multi-tenant pour les super admins et org admins      │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### 4 modes d'opération
+
+| Mode | Usage | Différenciateur |
+|------|-------|-----------------|
+| **EDTECH** | Formations structurées 21 jours via WhatsApp | Parcours pédagogique jour/jour + feedback IA |
+| **CRM_MARKETING** | Campagnes broadcast, gestion contacts | Listes de diffusion + templates approuvés Meta |
+| **AI_AGENT** | Bot autonome 24h/24 | RAG sur base de connaissance + personnalité configurée |
+| **CUSTOMER_SERVICE** | Support client avec escalade humaine | Mix bot + agent humain |
+
+---
+
+## 2. Base de données
+
+**Technologie :** PostgreSQL (Neon serverless) + Prisma ORM + pgvector extension
+
+### 2.1 Modèles principaux
+
+#### Organization (Racine multi-tenant)
+```
+id, name, slug
+mode: EDTECH | WEBHOOK | AI_AGENT | CRM_MARKETING | PEDAGOGY | CUSTOMER_SERVICE
+wabaId, metaBusinessId, systemUserToken, systemUserTokenIssuedAt
+customPrompt, personalityConfig (JSON), flowConfig (JSON), brandingData (JSON)
+subscriptionPlan: STARTER | GROWTH | SCALE | ENTERPRISE
+aiCreditsUsed, aiCreditsLimit, walletBalance, isHardStopped
+openAiApiKey, googleAiApiKey  (BYOK — chiffré au repos)
+```
+
+#### User (Apprenants & membres)
+```
+phone (unique par org), email, name
+role: STUDENT | ADMIN | ORG_MEMBER | ORG_ADMIN | SUPER_ADMIN
+language: FR | EN | ES | PT | WOLOF
+activity (secteur), currentStreak, longestStreak, lastActivityAt
+businessProfile → JSON (données entrepreneuriales)
+```
+
+#### Track & TrackDay (Contenu pédagogique)
+```
+Track: title, durationDays, language, isPremium, price
+TrackDay:
+  dayNumber (float — permet jour 1.5 "bis")
+  lessonText / audioUrl / imageUrl / videoUrl
+  exerciseType: TEXT | AUDIO | BUTTON
+  exercisePrompt, exerciseCriteria (JSON)
+  buttonsJson (choix interactifs multi-langue)
+  unlockCondition
+```
+
+#### Enrollment (État d'apprentissage)
+```
+userId + trackId (unique)
+status: ACTIVE | COMPLETED | DROPPED
+currentDay (float), lastActivityAt
+startedAt, completedAt
+```
+
+#### UserProgress (Machine à états exercice)
+```
+exerciseStatus: PENDING → PENDING_REMEDIATION → COMPLETED
+                        → PENDING_DEEPDIVE → COMPLETED
+                        → PENDING_REVIEW (révision humaine)
+badges (JSON), behavioralScoring (JSON)
+confidenceScore, iterationCount
+adminTranscription, overrideAudioUrl
+previousResponses (JSON array)
+```
+
+#### KnowledgeBaseEntry (RAG — Agent IA)
+```
+content (chunk texte), embedding (pgvector)
+metadata (JSON : source, page, title)
+organizationId
+createdAt
+```
+
+#### Message & Contact
+```
+Message: userId | contactId, direction (INBOUND/OUTBOUND)
+         mediaUrl, mediaId, status (SENT/DELIVERED/READ)
+         content, createdAt
+Contact: phoneNumber, name, attributes (JSON colonnes Excel dynamiques)
+         language, organizationId
+```
+
+#### WalletTransaction & UsageEvent
+```
+WalletTransaction: amount, type (TOP_UP/DEBIT_AI/DEBIT_BROADCAST)
+                   balanceAfter, byok (flag BYOK)
+UsageEvent: type (AI_TEXT/AI_AUDIO/AI_IMAGE/WHATSAPP_SENT)
+            feature (LESSON/FEEDBACK/DEEPDIVE/TRANSCRIPTION/CAMPAIGN...)
+            provider (GEMINI/OPENAI/META)
+            tokensIn, tokensOut, costUsd, durationMs
+```
+
+#### CampaignHistory & AnalyticsLog
+```
+CampaignHistory: status (SENT/DELIVERED/READ/FAILED), whatsappMessageId
+AnalyticsLog: eventType (CLICK/READ/RESPONSE), metadata
+```
+
+### 2.2 Enums clés
+- `Language` : FR, EN, ES, PT, WOLOF
+- `ExerciseStatus` : PENDING, PENDING_REMEDIATION, PENDING_REVIEW, COMPLETED, PENDING_DEEPDIVE
+- `SubscriptionPlan` : STARTER, GROWTH, SCALE, ENTERPRISE
+- `UsageFeature` : LESSON, FEEDBACK, DEEPDIVE, TRANSCRIPTION, IMAGE_ANALYSIS, CAMPAIGN, ONBOARDING, OTHER
+
+### 2.3 Particularités techniques
+- **pgvector** : Colonne `embedding` de type `Unsupported("vector")` — recherche cosinus pour RAG
+- **Multi-tenant via AsyncLocalStorage** : `tenantContext` injecte `organizationId` dans toutes les requêtes Prisma automatiquement
+- **Extension Prisma** : `packages/database/src/extension.ts` — auto-filtre chaque query par `organizationId`
+- **Modèles exclus du filtre tenant** : `Organization`, `TrainingData`, `NormalizationRule`
+
+---
+
+## 3. Backend — API Fastify
+
+**Localisation :** `apps/api/src/routes/`
+
+### 3.1 Authentification & Middleware
+
+```
+x-api-key (ADMIN_API_KEY, min 32 chars) → bypass JWT (appels worker→API)
+JWT via @fastify/jwt → { id, role, organizationId }
+rateLimit (plugin Fastify) → par route
+enforceOrgIsolation.ts → vérifie que l'org du JWT = l'org de la requête
+```
+
+### 3.2 Routes WhatsApp (`/v1/whatsapp/`)
+
+| Méthode | Route | Fonction |
+|---------|-------|----------|
+| GET | `/webhook` | Vérification Meta (hub.verify_token) |
+| POST | `/webhook` | Réception messages entrants (200 OK immédiat + queue) |
+| GET | `/templates` | Liste templates Meta pour l'org |
+| POST | `/templates` | Création template WhatsApp Business |
+
+**Fonctionnalités critiques :**
+- Vérification HMAC `X-Hub-Signature-256` sur le corps brut
+- Mise à jour `CampaignHistory` sur les status updates (DELIVERED/READ)
+- Forward asynchrone vers worker bridge (localhost:8082)
+
+### 3.3 Routes Admin (`/v1/admin/`)
+
+| Méthode | Route | Fonction |
+|---------|-------|----------|
+| GET | `/stats` | Stats dashboard (users, actifs, complétés, revenue) |
+| GET | `/users` | Liste paginée des utilisateurs |
+| GET | `/users/:id/messages` | Historique conversation |
+| GET | `/enrollments` | Inscriptions paginées |
+| GET | `/live-feed` | Exercices PENDING_REVIEW (révision humaine) |
+| POST | `/override-feedback` | Transcription manuelle + override audio admin |
+| GET/POST/PUT/DELETE | `/tracks` | CRUD parcours de formation |
+| GET/POST/PUT/DELETE | `/tracks/:id/days` | CRUD jours de formation |
+| GET | `/training/audios` | Audios en attente de correction STT |
+| POST | `/training/submit` | Soumission correction manuelle |
+| GET | `/training/suggestions` | Suggestions d'amélioration WER |
+| POST | `/training/apply-suggestions` | Application batch des règles |
+| POST | `/training/recalculate-wer` | Recalcul global WER avec règles |
+| POST | `/training/upload` | Upload + transcription audio |
+
+### 3.4 Routes IA (`/v1/ai/`)
+
+| Méthode | Route | Fonction |
+|---------|-------|----------|
+| POST | `/onepager` | Génération PDF one-pager + image IA |
+| POST | `/deck` | Génération PPTX pitch deck avec images IA |
+| POST | `/personalize-lesson` | Réécriture leçon selon activité utilisateur |
+| POST | `/tts` | Synthèse vocale texte → audio |
+| POST | `/transcribe` | Transcription audio → texte (confidence + isSuspect) |
+| POST | `/store-audio` | Archivage média vers R2 |
+| POST | `/generate-feedback` | Feedback exercice complet (2 branches) |
+| POST | `/extract-profile` | Extraction profil business depuis texte libre |
+| POST | `/chat` | Prompt système + question → réponse |
+| POST | `/crm/generate-campaign` | Message personnalisé par contact |
+| POST | `/crm/command` | Classification intention + routing action |
+| POST | `/crm/voice-command` | Commande vocale → action CRM |
+| POST | `/crm/send-bulk` | Envoi messages liste contacts |
+
+### 3.5 Routes Analytics (`/v1/analytics/`)
+
+| GET `/usage` | Messages, tokens estimés, coût |
+|---|---|
+| GET `/pedagogy` | Taux complétion, score moyen, temps moyen |
+| GET `/campaigns` | Funnel campagne (SENT → DELIVERED → READ) |
+
+### 3.6 Routes Organisations (`/v1/organizations/`)
+
+| CRUD orgs | `/` → liste, POST créer, GET/:id, PUT/:id |
+|---|---|
+| WhatsApp | `/:id/whatsapp-setup` — échange token OAuth Meta |
+| WhatsApp | `/:id/whatsapp-status` — validité token |
+| Personnalité | `PATCH /:id/personality` — mission, ton, nom bot |
+| Base de connaissance | `POST /:id/upload-kb` — upload + indexation |
+| KB stats | `GET /:id/kb-stats` — chunks, coverage |
+| KB gestion | `GET /:id/kb`, `DELETE /:id/kb/:entryId` |
+| Contacts | `POST /:id/contacts/import` — import Excel |
+| Contacts | `GET/DELETE /:id/contacts` — CRUD contacts |
+| Messages | `GET /:id/messages`, `POST /:id/messages/reply` |
+| Campagnes | `GET /:id/campaign-history` |
+
+### 3.7 Routes Billing (`/v1/billing/`)
+
+| GET `/summary` | Usage période courante + wallet |
+|---|---|
+| GET `/history?days=30` | Détail jour par jour |
+| GET `/breakdown` | Ventilation par fonctionnalité |
+| **POST `/chat`** | **Copilote IA admin (agentique)** |
+| POST `/template-generate` | Générateur template IA |
+| POST `/agent-test` | Test personnalité agent IA |
+| GET `/wallet` | Solde + 20 dernières transactions |
+| POST `/admin/allocate` | Recharge wallet (SUPER_ADMIN) |
+
+### 3.8 Routes Paiements (`/v1/payments/`)
+
+- `POST /initiate` — Initialiser session paiement
+- `POST /verify` — Vérifier paiement (via webhook gateway)
+- `GET /history` — Historique paiements org
+
+---
+
+## 4. Worker BullMQ
+
+**Localisation :** `apps/whatsapp-worker/src/`
+
+### 4.1 Queues
+
+| Queue | Jobs |
+|-------|------|
+| `whatsapp-queue` | inbound-message, inbound-media, send-message, send-content, enroll, nudge, broadcast, kb-process, generate-feedback, send-admin-audio-override |
+| `notification-queue` | email |
+
+**Retry policy :** 3 tentatives avec backoff exponentiel
+
+### 4.2 Chaîne de handlers (ordre strict)
+
+```
+WhatsAppLogic.handleIncomingMessage()
+  1. EntityResolver.resolve() → User/Contact/Org/Enrollment
+  2. Message log (async, non-bloquant)
+  3. Credit guard → WalletExhaustedError si solde = 0
+  4. AIAgentHandler.canHandle() → mode === AI_AGENT
+  5. OnboardingHandler.canHandle() → INSCRIPTION / sélection langue / secteur
+  6. CommandHandler.canHandle() → SEED / RECHARGE / DAY{N}_{ACTION}
+  7. NavigationHandler.canHandle() → SUITE / APPROFONDIR
+  8. ExerciseHandler.canHandle() → réponse exercice (texte/audio/image)
+  9. Fallback → message de bienvenue
+```
+
+### 4.3 Handler AIAgentHandler
+
+**Condition :** `organization.mode === 'AI_AGENT'`
+
+**Flux :**
+1. Construire system prompt depuis `customPrompt` + directive langue
+2. Si KB existe → `IndexingService.searchRelevantContext()` (top 3 chunks cosinus)
+3. Appel `AIPedagogyService.generateChat()` → réponse
+4. Envoi via `whatsapp-queue`
+
+**Lacunes :**
+- Pas de classification d'intention avant la recherche KB
+- Pas de seuil de pertinence (retourne toujours top-3, même peu pertinents)
+- Pas de mémoire conversationnelle (chaque message est traité indépendamment)
+- Pas de handoff humain automatique si confidence < seuil
+
+### 4.4 Handler OnboardingHandler
+
+**Flux :**
+1. Mot-clé `INSCRIPTION` → réinitialisation cascade (supprime enrollments/progress/responses)
+2. Sélection langue (LANG_FR, LANG_WO, LANG_EN, LANG_ES, LANG_PT)
+3. Sélection secteur (liste prédéfinie ou saisie libre)
+4. Auto-enroll via `defaultTrackId` (flowConfig)
+
+**Lacunes :**
+- Reset INSCRIPTION = suppression définitive (pas de soft-delete)
+- Secteurs hardcodés ou via flowConfig (fragile)
+- Pas de vérification téléphone / OTP
+
+### 4.5 Handler ExerciseHandler
+
+**Flux complexe :**
+1. Fetch `userProgress` pour le track actif
+2. Résolution du jour effectif (time-travel Redis OU currentDay)
+3. Validation longueur réponse (min 3 mots sauf boutons/images)
+4. Envoi message "spinner" (feedback en cours)
+5. Queue `generate-feedback` avec 40+ paramètres de contexte
+
+**Paramètres envoyés au générateur de feedback :**
+- exercicePrompt, exerciseCriteria, userResponse
+- previousResponses, businessProfile, language
+- iterationCount, exerciseStatus, dayNumber
+- trackTitle, userActivity, isDeepDive
+
+**Lacunes :**
+- Pas de détection de doublon dans les 30 secondes
+- Validation longueur simpliste (split whitespace)
+
+### 4.6 Handler FeedbackHandler
+
+**Flux :**
+1. `aiService.generateFeedback()` avec contexte complet
+2. **2 branches selon isQualified :**
+   - ❌ Échec : Message de relance + indication pour réessayer
+   - ✅ Succès : Feedback enrichi + conseils actionnables + prompt deep-dive
+3. Update atomique `exerciseStatus` AVANT envoi message (règle d'atomicité)
+4. Envoi via queue
+5. **Jour 11 spécial :** Extraction membre équipe depuis image si qualifié
+
+### 4.7 Scheduler (Tâches planifiées)
+
+```
+UTC 08:00 quotidien (= 08:00 Dakar) :
+  Pour chaque enrollment ACTIVE :
+    Si exercice PENDING + 24h sans activité → Nudge ENCOURAGEMENT
+    Si exercice PENDING + 72h sans activité → Nudge RESURRECTION
+    Sinon → Queue send-content (leçon du jour suivant)
+
+Chaque lundi 09:00 UTC :
+  Pour chaque org avec systemUserToken :
+    50 jours → Alerte WARNING (token va expirer dans ~10j)
+    55 jours → Alerte CRITICAL
+    60 jours → Alerte EXPIRÉ
+```
+
+**Lacunes :**
+- Nudges non personnalisés (même message par langue)
+- Pas de tentative de renouvellement token automatique
+- Alertes token uniquement dans les logs (pas d'email/push)
+
+### 4.8 Scoring comportemental
+
+**4 dimensions (0-100) :**
+- `discipline_financiere` — Gestion finances
+- `organisation` — Structure opérationnelle
+- `relation_client` — Qualité service client
+- `risque_management` — Gestion des risques
+
+**Niveaux :** Informel → Structuration → Organisé → Avancé
+
+### 4.9 ContentHandler (Livraison leçons)
+
+**Flux :**
+1. `sendLessonDay()` depuis `pedagogy.ts`
+2. Personnalisation IA (timeout 15s, fallback texte brut)
+3. Envoi visuel (vidéo → fallback image)
+4. Audio (TTS généré ou pré-enregistré)
+5. Boutons exercice interactifs
+6. **Logique de graduation :** Si pas de jour N+1 → COMPLETED + auto-enroll T{N+1}-LANG
+
+### 4.10 KBProcessor (Indexation base de connaissance)
+
+**Flux :**
+1. Parse document (PDF, Excel, site web HTML)
+2. Découpage en chunks (1000 chars, overlap 200)
+3. Génération embeddings via OpenAI batch
+4. Insertion pgvector via SQL brut (`prisma.$executeRaw`)
+
+**Lacunes :**
+- Pas de déduplication de chunks
+- Ré-indexation efface les anciens (pas de versioning)
+- Pas de progress tracking pour gros fichiers
+- Crawl web limité (depth 2, 10 liens/page)
+
+---
+
+## 5. SDK IA
+
+**Localisation :** `packages/ai-sdk/`
+
+### 5.1 Architecture multi-provider
+
+```
+AIService
+  └── ProviderRegistry
+        ├── GeminiProvider  (priority: 100) → TEXT, VISION, AUDIO
+        ├── OpenAIProvider  (priority: 50)  → TEXT, AUDIO, IMAGE, SPEECH
+        └── TenantProviders (priority: 1000) → BYOK par org
+```
+
+**Failover automatique :** Si le provider principal échoue, le suivant est essayé.
+
+### 5.2 Capacités par provider
+
+| Capacité | Gemini | OpenAI |
+|----------|--------|--------|
+| Texte (TEXT) | Flash/Pro | GPT-4o |
+| Vision (IMAGE) | Flash (inlineData base64) | GPT-4o Vision |
+| Transcription audio | — | Whisper |
+| Génération parole (TTS) | — | TTS-1 |
+| Génération image | — | DALL-E 3 |
+| Recherche web | Grounding API | — |
+
+**Note Gemini :** Toujours base64 `inlineData` pour la vision (jamais URL — instable).
+
+### 5.3 Coûts modèles (Mai 2026)
+
+| Modèle | Input (/1M tokens) | Output (/1M tokens) |
+|--------|-------------------|---------------------|
+| GPT-4o | $7.50 | $15.00 |
+| GPT-4o-mini | $0.15 | $0.60 |
+| Gemini Flash | $0.075 | $0.30 |
+| Gemini Pro | $3.50 | $10.50 |
+| Whisper | $0.006/min | — |
+
+### 5.4 Cache tenant
+
+- Configuration personnalité mise en cache Redis (TTL 1h)
+- Cache template PromptLoader en mémoire (durée de vie du processus)
+- **Pas** de cache au niveau requête LLM
+
+### 5.5 BYOK (Bring Your Own Key)
+
+- Plan SCALE uniquement
+- `openAiApiKey` et `googleAiApiKey` par org dans Prisma (chiffrés)
+- Providers tenant créés dynamiquement avec ces clés (priority 1000)
+- Débit wallet flagué `byok: true` (non facturé en crédits normaux)
+
+---
+
+## 6. Frontend Admin
+
+**Technologie :** React 18 + Vite + Tailwind CSS + react-i18next (FR/EN/ES/PT)
+
+### 6.1 Pages et composants
+
+#### Dashboard (`DashboardPage.tsx`)
+- Cartes stats : utilisateurs totaux, actifs, complétés, tracks, revenue
+- Table inscriptions paginée + tri
+- Export CSV inscriptions
+- Sélecteur d'organisation (multi-tenant)
+- Timeout 15s avec retry
+
+#### Analytics (`AnalyticsPage.tsx`)
+- Graphiques Recharts (Bar, Pie)
+- Usage IA : appels, tokens, coût FCFA
+- Pédagogie : taux complétion, score moyen, temps moyen
+- Campagnes : funnel SENT → DELIVERED → READ (4 couleurs)
+
+#### AI Agent Setup (`AIAgentSetup.tsx`)
+- Éditeur mission (coreMission)
+- Sélecteur de ton (Professionnel/Amical/Direct/Pédagogue) avec descriptions i18n
+- Recommandation ton selon mode org
+- Upload base de connaissance (PDF/DOCX/XLSX/CSV)
+- Stats KB : nb chunks, % coverage
+- Chat test en temps réel
+- Indicateur qualité KB (Excellent / Bon / Insuffisant)
+
+#### Billing (`BillingPage.tsx`)
+- Résumé wallet (crédits, FCFA, statut)
+- Graphique historique 30j
+- Ventilation par fonctionnalité
+- Alertes solde bas / service suspendu
+
+#### Contacts CRM (`ContactsPage.tsx`)
+- Import Excel avec colonnes dynamiques
+- Table contacts avec recherche/filtre
+- Envoi message direct depuis l'interface
+- Suppression bulk
+
+#### Templates (`TemplatesPage.tsx`)
+- Liste templates Meta avec statut (PENDING/APPROVED/REJECTED)
+- Création template avec générateur IA
+- Variables `{{1}}`, `{{2}}` dans éditeur
+- Aperçu avant soumission
+- Sélection catégorie (MARKETING/UTILITY)
+
+#### Tracks (`TrackListPage.tsx` + `TrackFormPage.tsx` + `TrackDaysPage.tsx`)
+- CRUD complet parcours de formation
+- Gestion jours (leçon + exercice + boutons)
+- Support multi-langue par contenu
+- Éditeur jours avec drag & drop (jour 1.5 supporté)
+
+#### Users (`UserListPage.tsx`)
+- Liste utilisateurs avec filtres
+- Détail conversation par utilisateur
+- Actions : override feedback, voir historique
+
+#### Training Lab (`TrainingLab.tsx`)
+- Révision manuelle transcriptions Whisper
+- Correction + calcul WER (Word Error Rate)
+- Suggestions normalization (règles de post-traitement)
+- Application batch des règles + recalcul global
+- Upload audio manuel pour test
+
+#### Knowledge Base (`KnowledgeBasePage.tsx`)
+- Gestion chunks KB
+- Suppression chunks individuels
+- Stats indexation
+
+#### Settings (`SettingsPage.tsx`)
+- Configuration mode, WhatsApp (WABA ID, Business ID, token)
+- Gestion clés API BYOK (plan SCALE)
+- Configuration avancée JSON (flowConfig)
+- Statut token WhatsApp avec alerte expiration
+
+#### CRM Inbox (`CrmInbox.tsx`)
+- Conversations temps réel
+- Réponse directe depuis l'interface
+- Statuts messages (lu/délivré)
+
+#### AdminChat (`AdminChat.tsx`)
+- Copilote IA contextuel par page
+- 6 pages : billing, settings, templates, agent, onboarding, general
+- Questions suggérées pré-remplies par page
+- **Agentic :** Peut changer le mode, mettre à jour la personnalité, lire la config
+- 4 langues (FR/EN/ES/PT)
+
+#### Campaign History (`CampaignHistoryPage.tsx`)
+- Historique campagnes avec funnel
+- Détail par campagne (SENT/DELIVERED/READ/FAILED)
+
+### 6.2 Internationalisation
+- 4 langues : FR (défaut), EN, ES, PT
+- Fichiers : `apps/admin/src/locales/{fr,en,es,pt}.json`
+- Hook `useTranslation()` partout
+- `LanguageSwitcher` composant global
+
+### 6.3 État de l'art UX actuel
+
+**Points forts :**
+- Design cohérent Tailwind CSS
+- Multi-tenant natif (sélecteur org)
+- Copilote IA intégré sur chaque page
+- Internationalisation complète
+
+**Lacunes UX :**
+- Pas de notifications temps réel (polling manuel)
+- Pas de mode sombre
+- Pas de raccourcis clavier
+- Pas de tour guidé (onboarding admin)
+- Pas de visualisation de la progression utilisateur en temps réel
+- Tableau de bord non personnalisable (widgets fixes)
+- Pas d'export PDF des rapports
+
+---
+
+## 7. Prompts & Templates IA
+
+**Localisation :** `packages/prompts/src/templates/`
+
+### 7.1 Templates disponibles
+
+| Fichier | Usage |
+|---------|-------|
+| `feedback-base.md` | Feedback exercice — structure de base |
+| `action-feedback-standard.md` | Feedback exercice — variante action |
+| `personalized-lesson.md` | Réécriture leçon selon profil utilisateur |
+| `business-profile-extraction.md` | Extraction profil business depuis texte |
+| `crm-campaign.md` | Génération message campagne personnalisé |
+| `crm-assistant-system.md` | System prompt assistant CRM |
+| `broadcast-router.md` | Routage messages broadcast |
+| `one-pager.md` | Génération PDF one-pager |
+| `pitch-deck.md` | Génération PPTX pitch deck |
+
+### 7.2 Système de compilation
+
+```typescript
+PromptLoader.compile(templateName, variables, personality)
+// Inject variables: {{variableName}}
+// Inject personality: {{botName}}, {{coreMission}}, {{toneDescription}}, {{constraints}}
+// Cache en mémoire (durée de vie du processus)
+```
+
+### 7.3 Personnalité par défaut (fallback)
+
+```
+botName: "XAMLÉ COACH"
+coreMission: "expert business pour entrepreneurs d'Afrique de l'Ouest"
+toneDescription: "direct, dynamique et encourageant. Style WhatsApp (gras *texte*, emojis)"
+constraints: ["JAMAIS ANGLAIS", "Ne jamais citer 'Manga Deaf'"]
+```
+
+---
+
+## 8. Tarification & Wallet
+
+**Table de prix :** `packages/database/src/credit-pricing.ts`
+
+```
+1 crédit = 10 FCFA
+
+WHATSAPP_CONVERSATION : 1 crédit (tout message entrant ou sortant)
+AI_TEXT              : 3 crédits (génération texte, non-BYOK)
+AI_AUDIO             : 2 crédits (transcription Whisper, non-BYOK)
+BROADCAST_PER_USER   : 3 crédits (par destinataire campagne)
+
+Seuils d'alerte wallet :
+  LOW      : 200 crédits (bannière orange)
+  CRITICAL : 50 crédits  (alerte rouge urgente)
+```
+
+**Plans :**
+
+| Plan | Crédits IA/mois | BYOK | SLA |
+|------|----------------|------|-----|
+| STARTER | 500 | ❌ | Standard |
+| GROWTH | 3 000 | ❌ | Standard |
+| SCALE | 10 000 | ✅ | Prioritaire |
+| ENTERPRISE | Illimité | ✅ | Dédié |
+
+---
+
+## 9. Lacunes & Dette technique
+
+### 9.1 Sécurité (priorité haute)
+
+| # | Problème | Impact | Solution recommandée |
+|---|----------|--------|---------------------|
+| S1 | `organizationId` depuis header (non JWT) | Usurpation d'identité possible | Extraire de `req.user.organizationId` uniquement |
+| S2 | Pas de rate-limiting webhook Meta | DDoS vulnérable | `@fastify/rate-limit` avec whitelist Meta IPs |
+| S3 | Tools IA agentiques sans garde-fous de rôle | N'importe quel admin change le mode | Exiger SUPER_ADMIN pour `change_organization_mode` |
+| S4 | Pas d'audit log | Impossible de tracer qui a changé quoi | Middleware Prisma → AuditLog sur toutes les updates critiques |
+
+### 9.2 Données & intégrité
+
+| # | Problème | Impact | Solution |
+|---|----------|--------|----------|
+| D1 | Pas de soft-delete | Perte irréversible sur INSCRIPTION reset | `deletedAt` sur User/Enrollment/UserProgress |
+| D2 | Pas de contrôle de concurrence | Double soumission exercice possible | Version field (optimistic locking) ou Redis lock |
+| D3 | Coûts IA estimés, pas réels | Billing inexact | API usage OpenAI/Google pour coûts réels |
+| D4 | Pas de validation schemas JSON | `personalityConfig`, `flowConfig` peuvent être malformés | Zod validation à l'entrée |
+
+### 9.3 IA & LLM
+
+| # | Problème | Impact | Solution |
+|---|----------|--------|----------|
+| A1 | Pas de retry sur échec LLM | Silence si timeout | Exponential backoff + dead-letter queue |
+| A2 | Pas de cache prompts | Recoût inutile sur leçons identiques | Redis cache par (lesson_id, activity) |
+| A3 | RAG naïf (top-3 sans seuil) | Réponses hors-sujet si KB sparse | Relevance threshold (cosine > 0.75) |
+| A4 | Pas de validation output LLM | `isQualified` pourrait être mal parsé | Structured outputs / JSON mode strict |
+| A5 | Pas de mémoire conversationnelle AI_AGENT | Contexte perdu entre messages | Redis sliding window (5 derniers messages) |
+| A6 | Transcription sans détection langue | Wolof mal transcrit | Whisper `language` param basé sur `user.language` |
+
+### 9.4 Performance & scalabilité
+
+| # | Problème | Impact | Solution |
+|---|----------|--------|----------|
+| P1 | N+1 dans `sendLessonDay()` | Lenteur avec > 100 inscriptions actives | Batch fetch avec Prisma `include` |
+| P2 | Embeddings synchrones pour gros fichiers | Timeout worker sur upload KB | Chunking + embeddings en batch asynchrone |
+| P3 | Pas de connection pooling explicite | Saturation pool Prisma (défaut 5) | `connection_limit` selon nb threads worker |
+
+### 9.5 Observabilité
+
+| # | Problème | Impact | Solution |
+|---|----------|--------|----------|
+| O1 | Pas de traceId propagé aux jobs async | Impossible de tracer une requête bout-en-bout | Passer traceId dans `job.data` |
+| O2 | Pas de distributed tracing | Vision nulle sur latences inter-services | OpenTelemetry (OTEL) collector |
+| O3 | Quota alerts dans logs seulement | Admin ne reçoit pas d'alerte solde bas | Email + push notification temps réel |
+
+### 9.6 Fonctionnalités manquantes
+
+| # | Fonctionnalité | Valeur | Effort |
+|---|---------------|--------|--------|
+| F1 | Scheduling campagnes (`sendAt`) | Élevée | Faible |
+| F2 | Segmentation contacts par tags | Élevée | Moyen |
+| F3 | A/B testing feedback prompts | Moyenne | Moyen |
+| F4 | Bulk enroll via API | Élevée | Faible |
+| F5 | Notifications temps réel admin (WebSocket/SSE) | Élevée | Moyen |
+| F6 | Export PDF rapports | Moyenne | Faible |
+| F7 | Mémoire conversationnelle AI_AGENT | Élevée | Faible |
+| F8 | Versioning KB | Moyenne | Moyen |
+| F9 | Rapport hebdomadaire par email | Élevée | Faible |
+| F10 | Tableau de bord personnalisable | Moyenne | Élevé |
+
+---
+
+## 10. Roadmap IA Agentique
+
+> **Définition :** Un agent IA est un système qui perçoit son environnement, prend des décisions, et exécute des actions de manière autonome — en boucle, avec des outils, sans intervention humaine sur chaque étape.
+
+### 10.1 Ce qui est déjà agentique (en production)
+
+| Fonctionnalité | Description | Outils utilisés |
+|---------------|-------------|-----------------|
+| **Copilote Admin** | Change le mode org, met à jour la personnalité | `change_organization_mode`, `update_ai_agent_personality`, `get_organization_settings` |
+| **Feedback exercice 2-branches** | Décide qualifié/non, génère feedback personnalisé | `generateFeedback()` → mise à jour DB → envoi message |
+| **RAG Agent IA** | Cherche dans la KB, formule réponse contextuelle | `searchRelevantContext()` → `generateChat()` |
+| **Graduation automatique** | Détecte fin de track, inscrit au niveau suivant | `ContentHandler` + détection T{N}→T{N+1} |
+| **Scheduler Nudge** | Analyse inactivité, envoie relances | `scheduler.ts` → BullMQ jobs |
+
+### 10.2 Agentique — Gains immédiats (0-4 semaines)
+
+#### 10.2.1 Mémoire conversationnelle pour AI_AGENT
+
+**Problème actuel :** Chaque message est traité indépendamment — l'agent "oublie" ce qu'il vient de dire.
+
+**Solution :**
+```typescript
+// Dans AIAgentHandler.ts
+const conversationHistory = await redis.lrange(`conv:${userId}`, 0, 9); // 10 derniers messages
+const messages = [
+  { role: 'system', content: systemPrompt },
+  ...conversationHistory.map(m => JSON.parse(m)),
+  { role: 'user', content: text }
+];
+await redis.lpush(`conv:${userId}`, JSON.stringify({ role: 'user', content: text }));
+// Après réponse :
+await redis.lpush(`conv:${userId}`, JSON.stringify({ role: 'assistant', content: answer }));
+await redis.ltrim(`conv:${userId}`, 0, 19); // Garder 20 messages max
+await redis.expire(`conv:${userId}`, 86400); // TTL 24h
+```
+
+**Impact :** Conversations cohérentes, expérience client transformée.
+
+#### 10.2.2 Alertes intelligentes solde wallet
+
+**Problème actuel :** L'admin apprend que le service est suspendu quand c'est trop tard.
+
+**Solution — Agent de surveillance financière :**
+```typescript
+// Dans scheduler.ts — ajouter toutes les heures
+const orgsAtRisk = await prisma.organization.findMany({
+  where: { walletBalance: { lte: 200 }, isHardStopped: false }
+});
+for (const org of orgsAtRisk) {
+  // Calculer burn rate 7 derniers jours
+  const weeklyDebit = ...; const daysLeft = org.walletBalance / (weeklyDebit / 7);
+  if (daysLeft < 3) await sendAlertEmail(org, daysLeft);
+  if (daysLeft < 1) await sendUrgentPush(org);
+}
+```
+
+#### 10.2.3 Rapport hebdomadaire automatique
+
+**Un email tous les lundis avec :**
+- Stats semaine (messages, complétion, coût)
+- Comparaison avec semaine précédente (+/- %)
+- Top 3 utilisateurs les plus actifs
+- Recommandation IA : "Votre taux de complétion a baissé de 15% — pensez à vérifier le contenu du Jour 7"
+
+**Implémentation :** Job cron lundi 07:00, génération HTML email via GPT-4o-mini, envoi via `notification-queue`.
+
+#### 10.2.4 Seuil de pertinence RAG
+
+```typescript
+// Dans AIAgentHandler.ts
+const chunks = await indexingService.searchRelevantContext(text, organizationId, { threshold: 0.75 });
+if (chunks.length === 0) {
+  // Répondre honnêtement "Je n'ai pas d'information sur ce sujet"
+  return "Je ne dispose pas d'informations précises sur ce sujet. Puis-je vous aider autrement ?";
+}
+```
+
+#### 10.2.5 Détection et handoff humain automatique
+
+**Pour mode CUSTOMER_SERVICE :**
+```typescript
+const needsHuman = await detectEscalation(text); // Sentiment très négatif, "parler à un humain", etc.
+if (needsHuman) {
+  await sendToHumanQueue(userId, organizationId, text);
+  await sendMessage(phone, "Je vous transfère à un conseiller humain. Merci de patienter.");
+}
+```
+
+### 10.3 Agentique — Gains stratégiques (1-3 mois)
+
+#### 10.3.1 Agent Créateur de Contenu
+
+**Problème :** Créer un Track de 21 jours prend des semaines manuellement.
+
+**Vision :** L'admin décrit son objectif pédagogique → l'agent génère tout le curriculum.
+
+**Outils :**
+```typescript
+tools: [
+  { name: 'create_track', description: 'Crée un Track avec titre et durée' },
+  { name: 'create_track_day', description: 'Crée un jour (leçon + exercice + critères)' },
+  { name: 'generate_lesson_content', description: 'Génère le texte de la leçon' },
+  { name: 'generate_exercise', description: 'Génère l\'exercice et ses critères de validation' },
+  { name: 'validate_curriculum', description: 'Vérifie la cohérence pédagogique du parcours' }
+]
+```
+
+**Flux agent :**
+1. Admin : "Crée un programme de 7 jours sur la gestion financière pour commerçants s��négalais"
+2. Agent → `generate_curriculum_outline()` → 7 thèmes progressifs
+3. Agent → `create_track()` → Track créé
+4. Boucle 7 fois → `create_track_day()` avec contenu généré
+5. Agent → `validate_curriculum()` → Vérification cohérence
+6. Agent → Rapport final : "Programme créé. 7 leçons, 7 exercices. Prêt à être publié."
+
+#### 10.3.2 Agent Optimiseur de Campagnes
+
+**Vision :** Analyse les performances passées et suggère les meilleures heures/jours/messages pour les prochaines campagnes.
+
+**Outils :**
+```typescript
+tools: [
+  { name: 'get_campaign_analytics', description: 'Récupère les métriques des campagnes passées' },
+  { name: 'segment_contacts', description: 'Segmente les contacts par comportement' },
+  { name: 'generate_message_variants', description: 'Génère des variantes de messages A/B' },
+  { name: 'schedule_campaign', description: 'Programme la campagne au meilleur moment' },
+  { name: 'measure_ab_results', description: 'Compare les résultats des variantes' }
+]
+```
+
+**Exemple d'analyse :**
+- "Les messages envoyés entre 10h-12h ont 34% de taux de lecture vs 12% le soir"
+- "Les messages < 80 caractères ont 2x plus de réponses"
+- "Le segment Dakar répond 40% mieux aux offres en wolof"
+
+#### 10.3.3 Agent Conseiller Pédagogique
+
+**Vision :** Analyse les résultats des apprenants et propose des interventions personnalisées à l'admin.
+
+**Outils :**
+```typescript
+tools: [
+  { name: 'get_cohort_analytics', description: 'Analyse les résultats d\'une cohorte' },
+  { name: 'identify_at_risk_students', description: 'Identifie les apprenants en difficulté' },
+  { name: 'suggest_intervention', description: 'Propose une action pour chaque apprenant à risque' },
+  { name: 'queue_personalized_nudge', description: 'Envoie un nudge personnalisé' },
+  { name: 'adjust_track_content', description: 'Modifie le contenu d\'un jour si trop difficile' }
+]
+```
+
+**Rapport hebdomadaire automatique :**
+```
+📊 Analyse de votre cohorte (semaine du 6-12 mai)
+- 23 apprenants actifs, 8 inactifs depuis > 3 jours
+- Jour 7 : 67% d'échec → Le critère est trop strict ou le contenu insuffisant
+- Recommandation : Assouplir les critères du Jour 7 OU envoyer un message d'encouragement
+- Action automatique : Nudge personnalisé envoyé aux 8 inactifs ✅
+```
+
+#### 10.3.4 Agent de Configuration Onboarding
+
+**Vision :** Guider un nouvel admin (organistion) à travers toute la configuration en conversation naturelle.
+
+**Flux conversationnel :**
+```
+Agent: "Bonjour ! Je vais vous aider à configurer Xamlé. Quel est votre secteur d'activité ?"
+Admin: "Nous faisons de la formation en comptabilité"
+Agent: "Parfait ! Je recommande le mode EDTECH. Avez-vous déjà un compte WhatsApp Business ?"
+Admin: "Non"
+Agent: → tool: create_whatsapp_embedded_signup_link()
+Agent: "Cliquez sur ce lien pour créer votre compte WhatsApp Business en 5 minutes : [lien]"
+Admin: [connecté]
+Agent: → tool: verify_whatsapp_connection()
+Agent: "✅ WhatsApp connecté ! Voulez-vous créer votre premier programme de formation maintenant ?"
+Admin: "Oui, sur les bases de la comptabilité, 10 jours"
+Agent: → tool: generate_curriculum(topic="comptabilité", days=10)
+Agent: "J'ai créé un programme de 10 jours. Voici le plan :
+        Jour 1 : Introduction aux bilans...
+        Approuvez-vous ce plan ?"
+```
+
+#### 10.3.5 Agent Détection de Fraude / Anomalies
+
+**Vision :** Surveiller automatiquement les comportements anormaux.
+
+**Signaux surveillés :**
+- INSCRIPTION répétée par même numéro (> 3x en 24h) → possible bot
+- Consommation crédits anormalement haute (> 2x moyenne 7j)
+- Messages envoyés depuis IPs non-Meta → webhook forgé
+- Contact importé en masse avec même numéro → déduplication manquante
+
+**Actions automatiques :**
+- Log d'alerte avec contexte complet
+- Notification email super admin
+- Possible suspension temporaire de l'org si score de fraude > seuil
+
+#### 10.3.6 Agent Génération de Knowledge Base
+
+**Vision :** L'admin décrit son activité en langage naturel → l'agent génère une FAQ et l'indexe automatiquement.
+
+```
+Admin: "Je gère un restaurant à Dakar. Nous servons des plats sénégalais traditionnels.
+        Prix : Thieboudienne 3500 FCFA, Yassa 2500 FCFA, Mafé 3000 FCFA.
+        Livraison disponible dans un rayon de 5km. Horaires : 11h-22h."
+
+Agent → generate_faq(description)
+→ "Q: Quels sont vos horaires ? R: Nous sommes ouverts de 11h à 22h."
+→ "Q: Faites-vous la livraison ? R: Oui, dans un rayon de 5km de notre restaurant."
+→ "Q: Quel est le prix du Thieboudienne ? R: 3500 FCFA."
+→ tool: index_knowledge_base(chunks=[...])
+Agent: "✅ Base de connaissance créée avec 12 questions/réponses. Votre agent IA est prêt !"
+```
+
+#### 10.3.7 Agent Multimodal — Analyse Qualité Exercices
+
+**Vision :** Analyser automatiquement la qualité des exercices et suggérer des améliorations.
+
+**Données analysées :**
+- Taux d'échec par exercice (> 40% → trop difficile ou critères trop stricts)
+- Temps moyen de réponse par exercice (> 30min → exercice trop complexe)
+- Distribution des scores (bimodale → exercice polarisant)
+- Mots les plus fréquents dans les réponses échouées → identifier les points de blocage
+
+**Sorties :**
+- Rapport "Top 3 exercices à améliorer cette semaine"
+- Suggestions de reformulation des critères
+- Proposition de contenu remédial (leçon supplémentaire)
+
+### 10.4 Agentique — Vision à long terme (3-12 mois)
+
+#### 10.4.1 Agent Autonome Multi-Étapes (ReAct Pattern)
+
+Implémentation du pattern **ReAct** (Reasoning + Acting) pour des workflows admin complexes :
+
+```
+Pensée : "L'utilisateur veut lancer une campagne de relance sur les clients inactifs"
+Action : get_inactive_contacts(days=30)
+Observation : 145 contacts inactifs
+Pensée : "Je dois segmenter par langue pour personnaliser les messages"
+Action : segment_by_language(contacts)
+Observation : 89 FR, 34 WOLOF, 22 EN
+Pensée : "Générer 3 variantes de message"
+Action : generate_messages(segments, goal="réactivation")
+Observation : messages générés
+Pensée : "Valider les templates puis envoyer"
+Action : validate_template_compliance(messages)
+Action : schedule_broadcast(contacts, messages, sendAt="2026-05-14T10:00:00Z")
+Résultat : "Campagne planifiée pour demain 10h. 145 messages. Coût estimé : 435 crédits."
+```
+
+#### 10.4.2 Personnalisation Adaptive (Apprentissage par renforcement léger)
+
+- Analyser quels styles de feedback → meilleurs résultats (score final)
+- A/B test automatique entre 2 variantes de prompt
+- Converger vers le prompt gagnant sans intervention humaine
+- **Technologie :** DSPy (Declarative Self-improving Python) ou OPRO (Optimizing Prompts by RL)
+
+#### 10.4.3 Agent Multilingue avec Détection Automatique
+
+- Détecter la langue de l'utilisateur sans qu'il le choisisse
+- Whisper `detect_language` + LangDetect sur texte
+- Basculer automatiquement (même en wolof)
+
+#### 10.4.4 Agent de Benchmarking Inter-Organisations (anonymisé)
+
+- Comparer anonymement les métriques de performance entre orgs similaires
+- "Votre taux de complétion (42%) est en dessous de la médiane (61%) pour les orgs EDTECH du secteur Finance"
+- Recommandations basées sur ce qui fonctionne pour les orgs similaires les plus performantes
+
+#### 10.4.5 Voice-First Admin Interface
+
+- Commandes vocales complètes pour gérer l'organisation
+- "Envoie un message de relance à tous les clients inactifs depuis 7 jours"
+- Transcription + interprétation + confirmation + exécution
+- Accessibilité pour admins sans formation technique
+
+---
+
+## 11. Dernières avancées technologiques applicables
+
+### 11.1 LLM & Génération
+
+#### Claude 4 (Anthropic, 2026)
+
+**Disponible aujourd'hui.** Models : `claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5`
+
+- **Prompt caching natif** (jusqu'à 90% de réduction de coût sur prompts répétitifs)
+  - Application directe : leçons personnalisées (même leçon, différents utilisateurs)
+  - Cache le system prompt + PLATFORM_KNOWLEDGE → économie ~$0.10/1000 appels
+- **Extended Thinking** (Opus 4.7) : Raisonnement profond pour évaluation complexe exercices
+  - Application : Scoring multi-critères exercices avancés (business plan, étude de marché)
+- **Computer Use** : Claude peut naviguer une interface web
+  - Application future : Agent qui vérifie le statut d'approbation Meta directement
+
+**Considération :** Passer progressivement les appels critiques (feedback) de GPT-4o à Claude Sonnet 4.6 (moins cher, aussi performant sur le français).
+
+#### GPT-4o-mini avec Structured Outputs
+
+**Disponible maintenant.** JSON Schema strict dans les réponses.
+
+```typescript
+const completion = await openai.chat.completions.create({
+  model: 'gpt-4o-mini',
+  response_format: {
+    type: 'json_schema',
+    json_schema: {
+      name: 'feedback_result',
+      schema: {
+        type: 'object',
+        properties: {
+          isQualified: { type: 'boolean' },
+          score: { type: 'integer', minimum: 0, maximum: 100 },
+          mainFeedback: { type: 'string', maxLength: 500 },
+          improvements: { type: 'array', items: { type: 'string' } }
+        },
+        required: ['isQualified', 'score', 'mainFeedback']
+      },
+      strict: true
+    }
+  }
+});
+```
+
+**Impact :** Éliminer tous les `try { JSON.parse(...) } catch {}` actuels dans le codebase.
+
+#### Gemini 2.0 Flash (Google, 2026)
+
+**Disponible maintenant.** 2x moins cher que Flash 1.5, plus rapide.
+
+- **Multimodal natif** : Image + texte + audio en une seule requête
+  - Application : Évaluer exercices photo (contenu + mise en page + professionnalisme en 1 appel)
+- **2M tokens context window** : Peut ingérer un track complet entier pour personnalisation cohérente
+- **Grounding avec Google Search** : Réponses factuelles vérifiées en temps réel
+  - Application : Agent IA qui répond à des questions avec des données récentes (prix marché, actualités secteur)
+
+#### Whisper v3 Large + Timestamps
+
+- Transcription avec horodatage mot par mot
+- Application : Identifier précisément où l'apprenant bute dans sa réponse orale
+- `language` parameter : Améliore la précision sur le wolof
+
+### 11.2 RAG & Base de Connaissance
+
+#### RAG Hiérarchique (HyDE + Reranking)
+
+**Technologie :** Cohere Rerank API ou cross-encoder local (bge-reranker)
+
+**Amélioration RAG actuelle :**
+```
+Actuel :  query → embedding → cosinus → top-3 chunks
+Amélioré: query → HyDE (génère une réponse hypothétique) → embedding → cosinus top-20
+          → Reranker (cross-encoder) → top-3 pertinents
+```
+
+**Impact :** Précision RAG +40% sur les questions ambiguës.
+
+#### pgvector 0.7 (Déjà disponible sur Neon)
+
+- **HNSW indexing** : Recherche 10x plus rapide sur > 100k vecteurs
+  ```sql
+  CREATE INDEX ON "KnowledgeBaseEntry" USING hnsw (embedding vector_cosine_ops)
+  WITH (m = 16, ef_construction = 64);
+  ```
+- **Quantisation des vecteurs** : Réduction 4x de la taille (int8 vs float32)
+
+#### Chunking Contextuel (Anthropic Contextual Retrieval, 2025)
+
+Au lieu de chunker naïvement par taille, ajouter le contexte du document à chaque chunk :
+
+```
+Chunk brut : "Le taux de TVA est 18%."
+Chunk contextuel : "Document: Guide fiscal Sénégal 2026 — Chapitre: TVA
+                    Le taux de TVA est 18%."
+```
+
+**Impact :** Réduction des "missed retrievals" de 67%.
+
+### 11.3 Infrastructure & Déploiement
+
+#### BullMQ 5.x — Worker Threads
+
+**Disponible maintenant.** Workers dans des threads Node.js séparés.
+
+```typescript
+new Worker('whatsapp-queue', processor, {
+  concurrency: 50,
+  useWorkerThreads: true, // ← Nouveau dans BullMQ 5
+  workerThreadsOptions: { execArgv: ['--max-old-space-size=512'] }
+});
+```
+
+**Impact :** +3x débit sur les jobs CPU-intensifs (embedding generation).
+
+#### Neon Branching pour tests
+
+- Créer une branche DB identique à la production en < 1s (copy-on-write)
+- Application : Tests d'intégration sur données réelles sans risque
+  ```bash
+  neon branch create --name test-$(date +%Y%m%d)
+  ```
+
+#### Cloudflare Workers pour le webhook Edge
+
+- Déplacer la réception webhook Meta sur Cloudflare Workers (< 10ms au lieu de ~100ms)
+- Validation HMAC à l'edge, mise en queue directe Redis
+- Zéro cold start, 100ms global response time
+
+#### OpenTelemetry (OTEL) — Tracing distribué
+
+```typescript
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+
+const sdk = new NodeSDK({
+  traceExporter: new OTLPTraceExporter({ url: process.env.OTEL_ENDPOINT }),
+  instrumentations: [getNodeAutoInstrumentations()]
+});
+```
+
+**Impact :** Visibilité complète webhook → queue → worker → DB → IA → réponse.
+
+### 11.4 UX / Frontend
+
+#### Server-Sent Events (SSE) pour updates temps réel
+
+Remplacer le polling manuel par SSE (sans WebSocket, plus simple avec Fastify) :
+
+```typescript
+// API
+fastify.get('/v1/admin/live', async (req, reply) => {
+  reply.raw.writeHead(200, { 'Content-Type': 'text/event-stream' });
+  const unsubscribe = pubsub.subscribe(`org:${orgId}:events`, (event) => {
+    reply.raw.write(`data: ${JSON.stringify(event)}\n\n`);
+  });
+  req.raw.on('close', unsubscribe);
+});
+
+// Frontend
+const eventSource = new EventSource('/v1/admin/live');
+eventSource.onmessage = (e) => updateDashboard(JSON.parse(e.data));
+```
+
+**Cas d'usage :**
+- Nouveau message reçu → update CRM Inbox en temps réel
+- Exercice complété → update compteur dashboard
+- Solde wallet change → alert immédiate
+
+#### React Server Components + Suspense
+
+Pour les pages analytics lentes (gros volumes de données) — rendu progressif sans skeleton loaders manuels.
+
+#### AI-powered Search dans le dashboard
+
+Recherche en langage naturel sur les données de l'org :
+- "Montre-moi les utilisateurs inactifs depuis 2 semaines"
+- "Quels sont les 5 exercices les plus échoués ce mois ?"
+- "Combien de crédits ont été consommés en transcription audio ?"
+
+**Technologie :** Text-to-SQL via GPT-4o-mini sur le schéma Prisma.
+
+### 11.5 IA Agentique — Frameworks
+
+#### Vercel AI SDK (avec tools)
+
+**Recommandé pour remplacer les appels OpenAI directs.** Supporte :
+- Streaming natif
+- Tool calling avec retry automatique
+- Multi-provider (OpenAI, Anthropic, Google)
+- `generateObject` avec Zod validation
+
+```typescript
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const result = await generateText({
+  model: openai('gpt-4o-mini'),
+  tools: { changeMode, updatePersonality, getSettings },
+  maxSteps: 5, // Boucle agentique max 5 étapes
+  messages: [...],
+});
+```
+
+#### LangGraph (pour agents multi-étapes complexes)
+
+Pour les workflows agentiques avec état persistant (ex: création curriculum) :
+
+```typescript
+const graph = new StateGraph({ channels: { messages, currentStep, orgId } })
+  .addNode('plan', planCurriculumNode)
+  .addNode('create', createTrackDayNode)
+  .addNode('validate', validateCurriculumNode)
+  .addEdge('plan', 'create')
+  .addConditionalEdges('validate', shouldContinue);
+```
+
+**Avantage :** Reprise sur erreur (le graph sauvegarde son état), debuggable.
+
+#### DSPy pour optimisation des prompts
+
+Au lieu de modifier manuellement les prompts, DSPy les optimise automatiquement :
+
+```python
+class FeedbackModule(dspy.Module):
+    def forward(self, response, criteria):
+        return self.generate(response=response, criteria=criteria)
+
+# Optimiser automatiquement sur 50 exemples validés
+optimizer = dspy.MIPROv2()
+optimized = optimizer.compile(FeedbackModule(), trainset=training_examples)
+```
+
+**Impact :** Amélioration mesurable du taux de qualification exercices sans ajustement manuel.
+
+### 11.6 Sécurité & Conformité
+
+#### Chiffrement BYOK avec AWS KMS ou Vault
+
+Les clés API des orgs doivent être chiffrées :
+
+```typescript
+// Utiliser une clé AES-256 dérivée par org
+const encryptedKey = await kms.encrypt({
+  KeyId: `alias/org-${organizationId}`,
+  Plaintext: Buffer.from(apiKey)
+});
+await prisma.organization.update({
+  where: { id: organizationId },
+  data: { openAiApiKey: encryptedKey.CiphertextBlob.toString('base64') }
+});
+```
+
+#### PII Redaction avant logs
+
+Les numéros de téléphone et clés API ne doivent jamais apparaître dans les logs :
+
+```typescript
+// Middleware de sanitisation
+const sanitize = (obj: any) => JSON.stringify(obj).replace(/\+?\d{10,15}/g, '[PHONE]');
+```
+
+---
+
+## 12. Matrice de priorisation
+
+### Impact × Effort
+
+| # | Fonctionnalité | Impact | Effort | Priorité |
+|---|---------------|--------|--------|----------|
+| 1 | **Mémoire conversationnelle AI_AGENT** | 🔴 Critique | 🟢 Faible | **P0 — Immédiat** |
+| 2 | **Structured outputs (isQualified JSON strict)** | 🔴 Critique | 🟢 Faible | **P0 — Immédiat** |
+| 3 | **Alertes wallet temps réel (email + push)** | 🔴 Critique | 🟢 Faible | **P0 — Immédiat** |
+| 4 | **Rapport hebdomadaire auto** | 🟠 Élevé | 🟢 Faible | **P1 — Cette semaine** |
+| 5 | **SSE temps réel dashboard** | 🟠 Élevé | 🟡 Moyen | **P1 — Cette semaine** |
+| 6 | **HNSW index pgvector** | 🟠 Élevé | 🟢 Faible | **P1 — Cette semaine** |
+| 7 | **Seuil pertinence RAG (0.75)** | 🟠 Élevé | 🟢 Faible | **P1 — Cette semaine** |
+| 8 | **Passage Claude Sonnet 4.6 pour feedback** | 🟠 Élevé | 🟡 Moyen | **P1 — Cette semaine** |
+| 9 | **Scheduling campagnes (sendAt)** | 🟠 Élevé | 🟢 Faible | **P1 — Cette semaine** |
+| 10 | **Soft-delete + audit trail** | 🟠 Élevé | 🟡 Moyen | **P2 — Ce mois** |
+| 11 | **Agent Créateur de Contenu** | 🔴 Critique | 🟡 Moyen | **P2 — Ce mois** |
+| 12 | **Détection handoff humain CUSTOMER_SERVICE** | 🟠 Élevé | 🟡 Moyen | **P2 — Ce mois** |
+| 13 | **Segmentation contacts par tags** | 🟠 Élevé | 🟡 Moyen | **P2 — Ce mois** |
+| 14 | **Text-to-SQL search dashboard** | 🟡 Moyen | 🟡 Moyen | **P3 — Q3 2026** |
+| 15 | **Agent Conseiller Pédagogique** | 🔴 Critique | 🔴 Élevé | **P3 — Q3 2026** |
+| 16 | **A/B testing feedback prompts (DSPy)** | 🟡 Moyen | 🔴 Élevé | **P4 — Q4 2026** |
+| 17 | **OpenTelemetry distributed tracing** | 🟠 Élevé | 🔴 Élevé | **P4 — Q4 2026** |
+| 18 | **ReAct Pattern campagnes autonomes** | 🔴 Critique | 🔴 Élevé | **P4 — Q4 2026** |
+| 19 | **Benchmarking inter-orgs anonymisé** | 🟡 Moyen | 🔴 Élevé | **Backlog** |
+| 20 | **Voice-first admin interface** | 🟡 Moyen | 🔴 Élevé | **Backlog** |
+
+### Prochaines 4 semaines — Plan d'action
+
+**Semaine 1 :** ✅ Complétée le 13/05/2026
+- [x] **Mémoire conversationnelle AI_AGENT** — Redis sliding window 20 messages (TTL 24h), historique injecté dans system prompt. → `apps/whatsapp-worker/src/handlers/AIAgentHandler.ts`
+- [x] **Structured outputs** — Déjà implémenté via `zodResponseFormat` + `FeedbackSchema` Zod en production dans `OpenAIProvider`.
+- [x] **HNSW index pgvector** — Script one-shot prêt → `packages/database/scripts/add-hnsw-index.ts`. Commande : `pnpm --filter @repo/database exec tsx scripts/add-hnsw-index.ts`
+- [x] **Seuil pertinence RAG (0.70)** — `searchRelevantContext()` filtre `WHERE similarity > 0.70`. Retourne `''` si vide → agent répond honnêtement. → `apps/whatsapp-worker/src/services/indexing.ts`
+- [x] **Alertes wallet** — Scheduler horaire + email Brevo si < 3 jours runway. Suppression 6h anti-spam Redis. → `apps/whatsapp-worker/src/scheduler.ts`
+- [x] **Rapport hebdomadaire** — Scheduler lundi 07:00 UTC : résumé appels IA, coût FCFA, trend vs semaine précédente, solde wallet. → `apps/whatsapp-worker/src/scheduler.ts`
+
+**Semaine 2 :** (en cours)
+- [ ] Scheduling campagnes (`sendAt` dans BroadcastHandler)
+- [ ] SSE pour updates temps réel CRM Inbox + Dashboard
+- [ ] Segmentation contacts par tags
+
+**Semaine 3 :** (à venir)
+- [ ] Passage Claude Sonnet 4.6 pour les appels feedback (coût / qualité)
+- [ ] Agent Créateur de Contenu (prototype — génère curriculum depuis description)
+
+**Semaine 4 :** (à venir)
+- [ ] Détection handoff humain (mots-clés + sentiment négatif)
+- [ ] Soft-delete User/Enrollment/UserProgress
+
+---
+
+## Conclusion
+
+Xamlé est une plateforme mature avec une architecture solide. Les opportunités de valeur les plus importantes se trouvent dans **trois axes** :
+
+1. **Fiabilité IA** : Mémoire conversationnelle + structured outputs + seuil RAG → transformation de l'expérience utilisateur AI_AGENT (aujourd'hui stateless et parfois hors-sujet, demain cohérent et précis).
+
+2. **Proactivité admin** : Alertes temps réel + rapports automatiques + agent conseiller → l'admin n'a plus besoin d'aller chercher l'information, elle vient à lui.
+
+3. **Agent Créateur de Contenu** : Générer un curriculum complet en 5 minutes au lieu de 2 semaines → démultiplicateur de productivité massif pour les orgs EDTECH.
+
+Ces trois axes combinés font de Xamlé une plateforme où **l'IA fait le travail à la place de l'admin**, pas seulement un outil que l'admin utilise.

packages/database/scripts/add-hnsw-index.ts

@@ -0,0 +1,36 @@
+/**
+ * One-time migration: adds HNSW index on KnowledgeBaseEntry.embedding
+ * for fast cosine-similarity search via pgvector.
+ *
+ * Run once against production:
+ *   pnpm --filter @repo/database exec tsx scripts/add-hnsw-index.ts
+ *
+ * Safe to re-run — uses CREATE INDEX IF NOT EXISTS.
+ * CONCURRENTLY means it does not lock the table during creation.
+ */
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+async function run() {
+    console.log('[HNSW] Ensuring pgvector extension is enabled...');
+    await prisma.$executeRawUnsafe(`CREATE EXTENSION IF NOT EXISTS vector;`);
+
+    console.log('[HNSW] Creating HNSW index on KnowledgeBaseEntry.embedding (this may take a minute)...');
+    await prisma.$executeRawUnsafe(`
+        CREATE INDEX CONCURRENTLY IF NOT EXISTS kb_embedding_hnsw_idx
+        ON "KnowledgeBaseEntry" USING hnsw (embedding vector_cosine_ops)
+        WITH (m = 16, ef_construction = 64);
+    `);
+
+    console.log('[HNSW] Setting ef_search for query-time accuracy/speed trade-off...');
+    await prisma.$executeRawUnsafe(`SET hnsw.ef_search = 40;`);
+
+    console.log('[HNSW] ✅ Index created. Cosine search is now ~10x faster on large knowledge bases.');
+    await prisma.$disconnect();
+}
+
+run().catch(err => {
+    console.error('[HNSW] ❌ Failed:', err);
+    process.exit(1);
+});