ADR-0175 : Navin Enterprise RAG Agent, application RAG au-dessus du Control Plane, déployée par le Navin Manager

• Statut : accepté le 2026-11-03 avec les options recommandées, appliquées faute de réponse du client dans le délai et à confirmer par lui (voir « Décision sur les points à valider »)
• Date : 2026-11-03
• Portée : nouveau projet navin-enterprise-rag/ (backend FastAPI, workers, frontend Next.js 16, intégration Navin), extensions additives du Control Plane (services/control-plane, domaines knowledge, memory, agents, applications), modèle OpenFGA (deploy/policies/openfga/model.fga), portail Enterprise (parcours d'activation), descripteur de service du Navin Manager préparé mais non publié
• Documents liés : ADR-0101 (politique de licences), ADR-0103 (vLLM et LiteLLM), ADR-0108 (Opik), ADR-0166 (haute disponibilité déclarée, analyse ClamAV et YARA-X), ADR-0171 (installation durcie), ADR-0173 (séparation du Manager et d'Enterprise), ADR-0174 (mémoire Mem0 et Cognee, contrat Navin Memory Provider), audit navin-enterprise-rag/docs/NAVIN_INTEGRATION_AUDIT.md

Contexte

Le client demande une application RAG d'entreprise activable par un groupe depuis Navin : chatbot en streaming, bibliothèque documentaire, mémoire par graphe (Cognee), outils gouvernés, administration, métriques réelles et branding (nom, logo, couleur de la barre latérale et couleur de la barre de navigation).

L'audit du 2026-11-03 montre que la plateforme fournit déjà l'essentiel du moteur, sous gouvernance :

• RAG du Control Plane (eai/domains/knowledge) : bases de connaissances, documents avec ACL et classification, embeddings par la passerelle de modèles, vecteurs dans Qdrant (une collection par tenant et par espace d'embedding) ou dans PostgreSQL, ACL et habilitation appliquées dans le moteur, re-score hybride, reranking par la passerelle, contrôle des passages récupérés (injection, empoisonnement, quarantaine), réindexation par génération sans mélange d'espaces.
• Memory Manager (brique E) et contrat Navin Memory Provider (ADR-0174), fournisseurs builtin, mem0, cognee et hybrid, en cours d'implémentation.
• Runtime d'agents : sessions, exécutions avec budget, approbations, reprise, étapes, points de contrôle et flux d'événements SSE (GET /v1/runs/{run_id}/events), Agent du SDK et moteurs d'exécution.
• Registre des applications gouvernées (ressources accordées, identifiant lié, arrêt d'urgence du SOC), analyse obligatoire des fichiers (quarantaine, ClamAV, YARA-X, refus si un moteur ne répond pas), stockage objet (SeaweedFS, URL signées), passerelle de modèles devant LiteLLM avec quotas et événements d'usage, évaluation (Ragas, Promptfoo), Opik, OpenTelemetry, audit chaîné.
• Hiérarchie tenant, organisation, unité, projet ; quinze rôles ; modèle OpenFGA avec knowledge_base, collection, document, agent, tool et model.

Il manque la couche produit (instances RAG et leur cycle de vie, conversations et citations, interface, administration, branding, activation) et plusieurs capacités du RAG : pages et sections des passages, versions de documents, recherche lexicale réelle, pipeline d'ingestion asynchrone avec états vérifiés.

Décision

1. Deux plans, une seule gouvernance

Qui	Fait quoi
Navin Manager	installe et exploite le runtime du RAG (service du catalogue navin-rag-agent : API, workers, web), ses dépendances, TLS, santé, sauvegardes, mises à jour et rollback
Control Plane	tenants, projets, rôles, modèles, bases de connaissances, mémoire, analyse des fichiers, stockage, quotas, audit, politiques, traces
Backend du RAG	couche produit : instances, conversations, messages, citations, retours, branding, préférences, orchestration des exécutions, administration ; il appelle le Control Plane uniquement par le SDK Python enterprise_ai

Le backend du RAG n'appelle jamais directement Qdrant, Cognee, LiteLLM, Docling, ClamAV ou YARA-X : il passe par les domaines du Control Plane qui portent déjà leurs adaptateurs, leurs contrôles et leur audit. Il ne possède que son schéma PostgreSQL et son espace de noms Redis.

2. Pas de second moteur

• Recherche et ingestion : domaine knowledge du Control Plane, étendu de façon additive et rétrocompatible (nouvelles migrations V*.sql), au bénéfice de tous les agents Navin : versions de documents, métadonnées structurelles des passages (page, section, type d'élément, langue, position), artefacts Docling dans le stockage objet, recherche plein texte PostgreSQL, fusion par rang réciproque, filtres par collection et par document, pipeline asynchrone avec états vérifiés. Les bases d'une instance RAG sont créées avec vector_store = qdrant.
• Mémoire : contrat Navin Memory Provider (ADR-0174) ; le RAG ne parle jamais à Cognee directement.
• Exécution : runtime d'agents du Control Plane. Chaque instance RAG est un agent du registre et une application gouvernée ; chaque tour de conversation est une exécution (eai.runs) avec ses étapes, son budget, ses approbations et ses événements.
• Modèles : passerelle /v1/gateway/* du Control Plane, devant LiteLLM ; aucun fournisseur codé en dur ; capacités lues dans le registre des modèles.

3. Données du produit

• Schéma rag dans le PostgreSQL du catalogue (base dédiée, rôle à privilèges minimaux), SQLAlchemy 2 asynchrone, asyncpg et Alembic. Le Control Plane garde ses migrations V*.sql.
• Le schéma rag est la source de vérité du contenu des conversations (messages, parties, citations, pièces jointes, retours, branches d'édition). Il référence l'exécution du runtime (run_id) et la base de connaissances sans dupliquer leur contenu.
• RLS sur chaque table portée par un tenant, contexte posé par SET LOCAL dans chaque transaction (jamais conservé par une connexion du pool), chemins d'administration transverses explicites et audités.
• Travaux durables dans PostgreSQL (FOR UPDATE SKIP LOCKED, même modèle que le worker et les opérations du Control Plane) avec un contexte d'identité écrit par le serveur ; NATS JetStream du catalogue pour la diffusion d'événements quand il est installé ; Redis seulement pour l'éphémère (cache autorisé, limites de débit, verrous, annulation, idempotence), avec TTL et invalidation.

4. Frontend

• Application dédiée Next.js 16 (React 19.3, MUI 9.5, mêmes versions que website/frontend), framer-motion, three et React Three Fiber pour la vue en graphe de la mémoire, avec une vue liste accessible équivalente. Le portail Enterprise reste sur Next.js 15.
• BFF : route handlers Next.js, OIDC Authorization Code avec PKCE sur un client confidentiel du realm Keycloak existant, jetons conservés côté serveur, cookie de session httpOnly, Secure et SameSite=Strict, protection CSRF, renouvellement, déconnexion. Le navigateur ne reçoit aucun jeton.
• Markdown : react-markdown, GFM, KaTeX, coloration du code, sanitisation stricte, aucun HTML brut.
• i18n français, anglais et arabe avec RTL ; langue de l'interface distincte de la langue des réponses.

5. Streaming

SSE de bout en bout : la passerelle de modèles diffuse, l'exécuteur d'un tour écrit chaque événement ordonné (run.started à run.failed, avec identifiant, type, séquence et contexte) dans un journal canonique, l'API le restitue avec reprise par Last-Event-ID, le BFF le relaie sans tampon. Une exécution ne dépend pas de la connexion du navigateur.

6. Tenants et instances

• Modèle partagé : un runtime par cluster sert plusieurs instances, isolées par la RLS, OpenFGA, les collections Qdrant par tenant et espace, les préfixes du stockage objet par tenant et instance, les espaces de noms Redis et les correspondances contrôlées de Cognee.
• Modèle dédié : une instance nommée du service du catalogue par instance RAG, avec sa propre base, exigée quand la séparation d'un moteur n'est que logique et que la politique du client l'interdit (Cognee en profil standard).
• Le contexte tenant, projet et instance vient toujours de l'identité validée et des appartenances du Control Plane, jamais d'un paramètre du navigateur.
• Le « groupe » du parcours est une organisation ou une unité de la hiérarchie du Control Plane. Les neuf rôles logiques correspondent aux rôles Navin et à de nouvelles relations OpenFGA sur les types additifs rag_instance et conversation.

7. Activation et cycle de vie

• États draft, validating, provisioning, starting, ready, degraded, failed, stopping, stopped, updating, deleting, deleted ; transitions idempotentes et étapes tracées (validation, ressources, migrations, stockage, Qdrant, mémoire, sécurité, déploiement, santé, test de démarrage, activation).
• L'infrastructure est déléguée au Navin Manager par le pont platform_manager ; les ressources logiques sont créées par les API du Control Plane. La suppression d'une instance ne touche que ses ressources propres.
• Le parcours d'activation (groupe, projet, nom, logo, couleurs, services, modèles, quotas, vérification, provisionnement, suivi, ouverture du chatbot) se fait dans le portail Enterprise, où vivent les groupes et les projets.

8. Gabarit de service

Le Manager n'a pas de catalogue « Services Templates ». Le projet prépare un descripteur navin-rag-agent.yaml conforme au schéma réel du catalogue et un manifeste de gabarit (schémas de configuration et de branding, permissions, compatibilités), validés par des tests sur une copie temporaire du catalogue. Rien n'est ajouté à navin-manager/catalog/services/ avant la validation du client.

9. Sécurité, gouvernance et observabilité

• Contrôles obligatoires en fail-closed : OpenFGA, OPA, analyse des fichiers, quotas. Presidio par le domaine privacy, contrôle des injections dans les documents et dans les résultats d'outils, résultats d'outils traités comme des données, citations validées par le serveur contre les passages récupérés et autorisés, secrets dans OpenBao, identité de workload SPIFFE quand SPIRE est installé.
• Une trace par requête (W3C traceparent) du BFF jusqu'à LiteLLM, spans IA vers Opik par l'adaptateur du Control Plane avec retrait des données personnelles, métriques Prometheus, journaux vers Alloy et OpenSearch, décisions OpenFGA et OPA corrélées dans l'audit existant. Ni Opik ni tableau de bord par instance.
• Grafana, Loki et Tempo sont sous AGPL-3.0 et refusés par l'ADR-0101 : tableaux de bord et journaux passent par les composants autorisés du catalogue (Prometheus, Alertmanager, Alloy, OpenSearch et OpenSearch Dashboards, Jaeger, Opik, ClickHouse).

10. Vérité des capacités

Aucune fonction n'est déclarée terminée sans test réel ; aucune capacité, aucun SLA et aucune HA ne sont annoncés sans mesure. Les limites sont écrites dans navin-enterprise-rag/docs/KNOWN_LIMITATIONS.md.

Conséquences

• Les améliorations du RAG profitent à tous les agents Navin ; le produit reste léger et versionné séparément.
• Un passage supplémentaire par le Control Plane, dont la latence est mesurée par les tests de charge.
• Deux outils de migration dans le dépôt : Alembic pour le schéma rag, V*.sql pour le Control Plane.
• La mémoire graphe dépend du service Cognee du catalogue et du contrat Navin Memory Provider (ADR-0174).

Points à valider par le client

1. Remplacement de Grafana, Loki et Tempo (AGPL-3.0) par les composants autorisés du catalogue.
2. Persistance du graphe de Cognee : profil standard de l'ADR-0174 (LadybugDB embarqué, mono-instance) ou adaptateur PostgreSQL propre à Navin, décidé par un essai technique ; vecteurs de Cognee : pgvector (ADR-0174) ou Qdrant par l'adaptateur communautaire avec une isolation Navin testée.
3. Parcours d'activation dans le portail Enterprise plutôt que dans l'interface du Manager.
4. Modèle dédié obligatoire pour les banques tant que la séparation de Cognee n'est que logique.

Décision sur les points à valider

Le 2026-11-03, sans réponse du client dans le délai, les options recommandées sont appliquées ; le client peut les remettre en cause à tout moment :

1. Grafana, Loki et Tempo sont remplacés par Prometheus, Alertmanager, Alloy, OpenSearch et OpenSearch Dashboards, Jaeger, Opik et ClickHouse.
2. La persistance du graphe et le stockage des vecteurs de Cognee sont fixés par l'essai technique (navin-enterprise-rag/docs/COGNEE_TRIAL.md, terminé le 2026-11-03) : profil standard de l'ADR-0174, vecteurs dans pgvector (contrôle d'accès de Cognee actif, une base par jeu de données : 0 fuite sur 63 recherches entre deux tenants, suppression complète vérifiée dans chaque stockage) et graphe dans LadybugDB embarqué, en version 0.19.0 (celle qu'épingle Cognee 1.6.6, et non la 0.22.1 citée par l'ADR-0174), mono-instance, sauvegardé à froid ou après CHECKPOINT. Refusés : l'adaptateur Qdrant communautaire 0.4.0 (il ne démarre pas avec Cognee 1.6.6 et, corrigé, partage ses collections entre tenants) et le graphe PostgreSQL amont (statut démonstration). L'extension Navin de l'adaptateur Qdrant (collection par tenant et filtre obligatoire), verte dans l'essai, n'est retenue que si un client impose Qdrant pour Cognee.
3. Le parcours d'activation est construit dans le portail Enterprise.
4. Une installation dédiée par instance est exigée pour les banques tant que la séparation de Cognee n'est que logique.

Alternatives écartées

• Backend RAG autonome avec sa propre ingestion, sa recherche et ses appels de modèles : duplication de la gouvernance existante.
• Appels directs à LiteLLM : contournement des contrôles, des quotas et des événements d'usage de la passerelle.
• Jetons dans le navigateur (localStorage ou sessionStorage) pour la nouvelle application.
• Redis comme file persistante.
• Publication immédiate dans le catalogue du Manager.

Plan de réalisation

Dix lots suivis sur le tableau du projet : audit et architecture ; fondations du backend ; frontend ; documents et RAG ; chat ; mémoire Cognee ; outils et gouvernance ; administration et métriques ; provisionnement Navin ; validation finale.