Lot 2 — Chatbot RAG : spécification

Spécification de l'assistant documentaire : une interface web de questions/réponses sur la doc, qui réutilise le cœur RAG (retrieval) et Claude (génération), avec citations. Rattaché au cadre : specs/ia-vitrine.md. Socle : specs/ia-coeur.md. Statut : implémenté en prod (telaria.dev) — voir « Surfaces livrées » ci-dessous.

1. Objectif et périmètre

Le chatbot est la surface visible de l'initiative : poser une question en langage naturel et obtenir une réponse fondée sur la doc, avec ses sources. C'est aussi un actif réutilisable : pointé sur la doc d'un autre projet, il devient l'assistant de ce projet.

• Réutilise le retrieval du cœur (L0) et le port LLM (Claude).
• Usage initial : démos par l'auteur (pas d'accès public) → latence tolérable, faible volume.

Périmètre V1 : page de chat, question → retrieval → génération Claude → réponse avec citations. Hors V1 : historique multi-sessions, comptes, multi-projets simultanés, retour utilisateur (feedback).

Surfaces livrées (« l'assistant » et « le chat »)

La spécification ci-dessus est implémentée et déployée (telaria.dev) sous deux surfaces qui partagent le namespace App\Chat et le cœur RAG (retrieval) ; seule la résolution des réglages diffère :

• « L'assistant » — page publique /assistant (ex-/chat), vocation démo / exploration : le visiteur édite les réglages en live (modèle, k, seuil, température, max_tokens, historique), stockés en session (un jeu par navigateur). Résolution : forAssistant() (.env + session).
• « Le chat » — assistant embarqué dans le viewer /docs (offcanvas rétractable), vocation assistance de production : aucun réglage visiteur, paramètres figés en back-office (/admin/chat/params, entité ChatConfig). Les sources d'une réponse sont des liens qui rechargent le document dans le viewer (navigation AJAX). Résolution : forEmbeddedChat() (config BO).

Décisions d'implémentation : pas de streaming en V1 (rendu serveur) ; garde-fou hors-périmètre (score sous le seuil → « pas dans la doc », sans appel LLM). Réf. coordination codexia #40/#41.

2. Flux

Question ──▶ Retrieval (cœur L0) ──▶ Assemblage du prompt ──▶ Claude (génération) ──▶ Réponse + citations
            top-k passages              system + contexte         (streaming optionnel)
            + sources                   + question

3. Composants

3.1 Front (Symfony / Twig)

• Page de chat : zone de saisie, fil de la conversation, réponse avec liste des sources.
• Amélioration progressive : un envoi form POST sans JavaScript renvoie une réponse complète (rendu serveur). Le JavaScript (streaming, confort) est un plus, pas un prérequis.
• Design system existant (design.md, ui.md, bootstrap.md) ; conformité RGAA 4.1 AA (accessibility.md).

3.2 Orchestration (ChatService)

1. Récupère les passages pertinents via le RetrievalService du cœur (top-k + sources).
2. Assemble le prompt : system + contexte (passages + sources) + question.
3. Appelle le port LLM (Claude) et récupère la réponse.
4. Retourne la réponse et la liste des sources utilisées.

3.3 Port LLM (Claude)

• Abstraction d'appel (modèle, max tokens, température basse pour la factualité).
• Prompt caching sur le bloc stable (system + contexte) pour réduire le coût (cf. cadre §3).

4. Conception du prompt

• System prompt : rôle (« assistant documentaire »), consignes strictes :
  • répondre uniquement à partir du contexte fourni ;
  • citer les passages utilisés ;
  • si le contexte ne contient pas la réponse, le dire (ne pas inventer).
• Contexte : les passages récupérés, chacun avec sa source (chemin, section).
• Prompt caching : le bloc system (+ contexte, si réutilisé) est marqué pour mise en cache.

5. Citations

Chaque réponse s'accompagne de ses sources : pour chaque passage utilisé, chemin + section + lien vers le document. Une réponse sans source pertinente est signalée comme telle (voir §8).

6. Périmètre V1 / hors V1

7. Accessibilité et design

• RGAA 4.1 AA : structure en landmarks, libellés explicites, focus visible et logique, pas de piège clavier.
• Réponse rendue dans une région aria-live="polite" pour annonce aux lecteurs d'écran.
• Cohérence visuelle avec le design system ; états (chargement, erreur) accessibles.

8. Gouvernance et garde-fous

• Réponses ancrées : si aucun passage pertinent (score sous un seuil), répondre « cette information n'est pas dans la documentation » plutôt que d'inventer (cf. fiche 6.1 — hallucinations).
• Citations obligatoires : pas d'affirmation sans source dans le périmètre documentaire.
• Pas de données personnelles ; coût maîtrisé (prompt caching, quotas) ; le RAG bien fait est détaillé en fiche 4.3.

9. Configuration

• chatbot.model : modèle Claude.
• chatbot.k : nombre de passages récupérés.
• chatbot.temperature : basse (factualité).
• chatbot.max_tokens : borne de la réponse.
• chatbot.score_threshold : seuil en deçà duquel on répond « hors périmètre ».
• chatbot.prompt_cache : activation du caching.

10. Tests unitaires (cas concrets)

Orchestration (ChatService)

• La question est transmise au RetrievalService (mocké) ; le prompt assemblé contient les passages récupérés et la question.
• Retrieval vide (ou scores sous le seuil) → réponse « hors périmètre », sans appel au LLM.
• La réponse expose les sources des passages effectivement utilisés (aucune source absente du contexte).

Port LLM (Claude mocké)

• Les paramètres (modèle, température, max tokens) sont transmis.
• Le prompt caching est activé sur le bloc stable.

Front (amélioration progressive)

• form POST sans JS → réponse complète rendue côté serveur.
• La réponse est rendue dans une région aria-live ; les liens de sources sont présents et corrects.

Garde-fous

• Aucune source inventée : toute source citée provient du contexte récupéré.
• Une question hors doc déclenche le message « pas dans la documentation ».

Accessibilité

• Landmarks présents, libellé du champ de saisie, ordre de tabulation logique, focus visible.

11. Démo

• Scénario : 3-4 questions couvrant des thèmes de la doc (ex. RGPD, MCP, accessibilité) → réponses sourcées.
• Capture d'écran pour la vitrine (accès public non requis).

12. Production documentaire d'accompagnement (doctrine)

13. Points ouverts (à trancher à l'implémentation)

1. Streaming : SSE / Mercure, ou réponse complète seulement en V1 ?
2. Persistance de l'historique : session uniquement, ou stockage ?
3. Seuil de score « hors périmètre » : valeur à calibrer.
4. Sélecteur de projet (multi-projets) : V1 mono-projet, à étendre ensuite.

Documents liés

• Cadre : specs/ia-vitrine.md
• Cœur RAG (retrieval) : specs/ia-coeur.md
• Serveur MCP (autre surface) : specs/ia-mcp.md
• Fiche RAG : agents/4-interagir-avec-l-ia/4-3-le-prompt-engineering-niveau-avance.md
• Fiche hallucinations : agents/6-ethique-risques-et-limites/6-1-les-hallucinations.md

Implémentation

Historique des décisions