Assistant RAG (Admin) + Test RAG — workflow “tester → analyser → proposer → appliquer”

TL;DR

Cette fonctionnalité (UI admin) permet de :

1. Tester un comportement RAG en conversation multi‑tours (comme une app externe type Aurora Bot).
2. Envoyer la session à l’Assistant RAG (admin‑only).
3. Décrire un reproche / objectif (“ce qui ne va pas”).
4. Lancer une analyse basée sur les données réelles (logs Postgres + extraits Qdrant + prompts/réglages courants).
5. Obtenir des propositions de changements (service / workspace overlay).
6. Générer un preset (draft).
7. Appliquer (ou rollback) uniquement après validation.

Route UI : /{locale}/admin/assistant-rag (admin only).

Concepts & identifiants

• Service = source_app : scope “métier” (gouvernance + prompts + settings).
• Workspace = workspace : sous‑contexte au sein d’un service (overrides RAG/prompt possibles).
• Application appelante = caller_app : séparation logique entre applications clientes (Aurora Bot, Scraper, etc.).
• Conversation = thread_id : identifiant stable sur plusieurs tours.
• Tour = une requête POST /api/query (loguée dans queries_log).

Le Test RAG repose sur la même API que les apps externes : POST /api/query.

Exemple minimal :

{
  "query": "Résume le document X",
  "caller_app": "aurora_bot",
  "thread_id": "thread-123",
  "source_app": "operations",
  "workspace": "projets",
  "language": "fr"
}

Onglet “Test RAG” (conversation multi‑tours)

Objectif : reproduire fidèlement une conversation “réelle” avec les réglages actuellement en place.

Comportement

• Un bouton New thread redémarre une conversation (nouveau thread_id).
• Tant qu’un thread est actif, l’UI bloque le changement de source_app / workspace / modèle pour éviter de mélanger les traces.
• Le Test RAG est volontairement non-stream (simplicité / coûts dev).

Debug retrieval (dernier tour)

Après un envoi, le Test RAG expose une trace retrieval sur le dernier tour via :

• GET /api/admin/rag-tests/trace/{query_id}

Cette trace sert d’“evidence” au moment de l’analyse.

“Envoyer à l’Assistant RAG”

Quand tu cliques Envoyer à l’Assistant RAG, l’UI n’envoie pas un export client contenant tout le contenu. Elle envoie surtout des IDs et sélecteurs (ex. thread_id, caller_app, source_app, workspace, modèle…) afin que le backend puisse relire :

• les tours de conversation depuis Postgres (queries_log),
• les top hits retrieval depuis les logs,
• les chunks depuis Qdrant (extraits),
• les réglages et prompts courants (service + overlay workspace).

Résultat : l’analyse est basée sur ce que Nexus a réellement fait, pas sur un export client partiel.

Onglet “Assistant RAG” (admin‑only)

Cet onglet est conçu pour produire des recommandations professionnelles et “auditables”.

(Optionnel) Aurora Scraper

Si vous utilisez Aurora Scraper pour faire de la recherche web et envoyer des lots de pages vers Nexus :

• Configurez NEXT_PUBLIC_AURORA_SCRAPER_URL dans le .env (wizard : question dédiée).
• L’UI affiche alors un bloc “Aurora Scraper” avec :
  • un bouton “Ouvrir Aurora Scraper”
  • la destination d’import recommandée (source_app=__rag_assistant, workspace=sources, caller_app=aurora_scraper)

Curation → Runbooks (V1)

Une fois un batch importé dans __rag_assistant/sources, l’UI affiche un bloc “Curation → Runbooks” :

1. Sélectionner un batch sources (dernier lots envoyés par Scraper).
2. Cliquer Prévisualiser : Nexus propose une liste de runbooks (titres + objectifs + sources).
3. Ajuster / supprimer des runbooks (validation humaine).
4. Cliquer Publier : Nexus génère les .md et lance l’ingestion dans __rag_assistant/runbooks.

Important :

• Les sources brutes (workspace=sources) sont exclues du retrieval de l’Assistant RAG par défaut.
• Les runbooks publiés sont la source d’expertise “stable” et “auditables” (section “Sources” + URLs).

Étape 1 — Session importée (lecture seule)

La session importée affiche :

• les identifiants (caller_app, thread_id, source_app, workspace, modèle),
• un résumé “trace” (dernier tour) quand disponible.

Étape 2 — Reproche / objectif (obligatoire)

Exemples :

• “Réponse trop longue, je veux un format TL;DR + 5 bullets.”
• “Le modèle invente, je veux refus strict si pas de sources.”
• “Retrieval loupe des documents, je veux plus de diversité (MMR) sur ce workspace.”

Étape 3 — Analyze

L’analyse est déclenchée via :

• POST /api/admin/rag-assistant/analyze

Elle agrège :

• la conversation (tours) relue dans queries_log,
• les traces retrieval + extraits Qdrant (evidence),
• les prompts courants (service + overlay workspace),
• un snapshot des settings RAG courants.

Étape 4 — Propositions, puis “Generate preset”

Après analyse, l’assistant produit des propositions de changements (service ou workspace overlay).

Important :

• aucun auto‑apply : l’assistant ne modifie pas la base sans validation explicite.
• “Generate preset” produit un preset (draft) à vérifier.

Étape 5 — Apply / Rollback

Une fois validé :

• POST /api/admin/rag-assistant/apply applique le preset en base (service / workspace overlay).
• POST /api/admin/rag-assistant/rollback annule le dernier apply.

Base de connaissance interne de l’Assistant RAG (assistant_kb/)

L’Assistant RAG peut s’appuyer sur une base interne “admin‑only” distincte des docs utilisateur :

• Dossier repo : assistant_kb/
• Rafraîchissement : POST /api/admin/rag-assistant/kb/refresh
• Cible : collection/document store interne __rag_assistant

Objectif : garder docs/ pour les utilisateurs, et centraliser la connaissance “interne” exploitable par l’assistant (architecture, conventions, runbooks, sans secrets).

Dépannage rapide

“Je ne vois pas ma conversation dans l’analyse”

• Vérifier que la conversation a bien un thread_id stable.
• Vérifier que caller_app est constant sur le thread.
• Vérifier que les tours apparaissent dans queries_log (monitoring requêtes).

“L’analyse ne voit pas les bons documents”

• Vérifier la trace retrieval du dernier tour (/api/admin/rag-tests/trace/{query_id}).
• Vérifier les workspaces : un mauvais workspace = mauvais scope de retrieval.