ADR-0185 : Navin Fraud & Anomaly Investigation Agent, couche produit de détection et d'investigation au-dessus du Control Plane

• Statut : accepté le 2026-11-04 ; les choix ouverts ont été tranchés par l'utilisateur le 2026-11-04 (voir « Décisions de l'utilisateur »)
• Date : 2026-11-04
• Portée : nouveau projet navin-fraud-investigation/ (backend FastAPI, workers, écrans dans le frontend commun des agents sectoriels (ADR-0180), intégration Navin), domaine additif fraud du Control Plane (services/control-plane/src/eai/domains/fraud, migrations V230 à V239), types OpenFGA additifs, paquet OPA eai.fraud, parcours d'activation du portail Enterprise, gabarit de service préparé mais non publié
• Documents liés : ADR-0101 (politique de licences), ADR-0103 (vLLM et LiteLLM), ADR-0108 (Opik), ADR-0111 (stockage sans MinIO), ADR-0113 (Redis cache seulement), ADR-0114 (PostgreSQL source de vérité), ADR-0116 (audit chaîné), ADR-0166 (analyse ClamAV et YARA-X), ADR-0174 (mémoire Mem0 et Cognee), ADR-0175 (modèle du RAG Agent), audit navin-fraud-investigation/docs/NAVIN_INTEGRATION_AUDIT.md

Contexte

Le client demande un agent de détection et d'investigation des fraudes et des anomalies pour trois secteurs (banque, assurance, retail) : ingestion d'événements métier autorisés, règles versionnées, modèles statistiques et de Machine Learning, scores explicables, corrélation, alertes, graphe des relations, analyse des justificatifs, dossiers d'enquête, preuves et chaîne de conservation, revue humaine, actions contrôlées, copilote d'investigation, rapports et indicateurs.

L'audit du 2026-11-04 montre que la plateforme fournit déjà la gouvernance (identité, tenants, RLS, OpenFGA, OPA, quotas, audit chaîné, DLP et Presidio), le runtime d'agents (exécutions, sous-agents, outils, approbations, SSE), l'ingestion documentaire (Docling, Qdrant, ClamAV, YARA-X), la mémoire Cognee, les scellés et legal holds (/v1/evidence/*), le stockage objet avec verrouillage déclaré, le Connector Hub et le modèle de cycle de vie rag_agent. Il manque la couche produit, les connecteurs métier (core banking, sinistres, e-commerce, POS, OMS, paiement : absents) et tout moteur de détection.

Décision

1. Couche produit, même modèle que l'ADR-0175

Qui	Fait quoi
Navin Manager	installe et exploite le runtime (API, workers, web), TLS, santé, sauvegardes, mises à jour, rollback
Control Plane	tenants, projets, rôles, modèles de langage, bases de connaissances, mémoire, analyse des fichiers, stockage, scellés, quotas, audit, politiques, traces ; domaine fraud pour les instances et leur cycle de vie
Backend du FAI	ingestion, détection, scoring, alertes, graphe, dossiers, preuves, décisions, actions, copilote, rapports, KPI ; il joint le Control Plane uniquement par le SDK Python enterprise_ai

Le backend ne parle jamais directement à Qdrant, Cognee, LiteLLM, Docling, ClamAV ou YARA-X. Il possède son schéma PostgreSQL fraud (Alembic, comme le schéma rag) et son espace de noms Redis. Ports de développement : backend 8474, frontend 3474.

2. Un moteur commun, trois packs

Un seul moteur (ingestion, règles, features, modèles, scoring, corrélation, alertes, graphe, dossiers) et trois packs sectoriels versionnés et validés par schéma (banque, assurance, retail) : règles, features, modèles, politiques de scoring, types d'alertes et de dossiers, workflows, actions, KPI et rapports. Une instance active un pack et le personnalise sans code.

3. Détection indépendante du LLM

• La détection est faite par des règles déterministes et des modèles statistiques ou ML. Un LLM n'est jamais un moteur de scoring, ne modifie jamais une règle, un seuil ou une politique de production, et n'assiste que l'investigation (synthèse, recherche, rédaction), toujours par la passerelle /v1/gateway/* devant LiteLLM.
• Les règles sont écrites dans un langage structuré validé par schéma (contracts/v1/fraud-rule.schema.json) et exécutées par un interpréteur déterministe : jamais d'eval, jamais de code fourni par un utilisateur.
• Chaque résultat enregistre les versions des features, des règles, des modèles et de la politique de scoring.
• Un score n'est jamais une décision : « fraude confirmée » est réservée à un dossier validé par un humain habilité selon la procédure.

4. Pile ML

• scikit-learn 1.9.1 (BSD-3-Clause) pour les scores robustes, Isolation Forest et les classifieurs, XGBoost par le paquet xgboost-cpu 3.4.1 (Apache-2.0 ; le paquet xgboost est écarté car il tire nvidia-nccl-cu13 sous licence NVIDIA), SHAP 0.54.1 (MIT) pour les explications, NumPy 2.5.4, pandas 3.1.0, SciPy 1.18.1 (BSD). Licences relevées sur PyPI le 2026-11-04 ; tqdm (dépendance de SHAP, MPL-2.0 et MIT) est déjà couvert par catalog/licence-exceptions.yaml.
• Pas de LLaMA-Factory : aucun affinage de modèle de langage dans ce produit.
• Jeux de données versionnés avec séparation temporelle, aucune fuite entre entraînement et validation, aucun réentraînement automatique sur les alertes clôturées, dossiers non investigués jamais comptés comme légitimes.

5. Artefacts de modèles

Le registre /v1/models décrit des modèles de langage et le Navin Trusted Hub distribue des services : ni l'un ni l'autre ne décrit un classifieur tabulaire. Les artefacts sont écrits dans le stockage objet du Control Plane (/v1/storage/profiles, SeaweedFS ou stockage du client, jamais MinIO), avec une empreinte SHA-256 et une signature Ed25519 dont la clé vit dans OpenBao. Le registre des versions (état, approbation, shadow, canary, rollback, retrait) est dans le schéma fraud. Un artefact dont l'empreinte ou la signature ne vérifie pas n'est jamais chargé.

6. Flux durables et données

• Aucun nouveau broker : travaux durables dans PostgreSQL (FOR UPDATE SKIP LOCKED, identité signée, retry, backoff, dead letter, rejeu) comme le RAG Agent, NATS JetStream du catalogue pour la diffusion quasi temps réel quand il est installé (eai/integrations/nats.py).
• PostgreSQL est la source de vérité du produit, les systèmes métier restent sources de vérité de leurs données : le FAI garde des références et des caractéristiques calculées plutôt que des copies sensibles ; références de paiement tokenisées seulement, jamais de CVV, de PIN ni de donnée d'authentification interdite.
• RLS forcée sur chaque table de tenant, partitionnement par date des événements et des scores, outbox, rétention et legal holds.
• Redis cloisonné par tenant pour l'éphémère seulement (cache de règles, fenêtres de features, limitation de débit, idempotence, verrous, déduplication), jamais comme stockage définitif.

7. Graphe d'investigation

Le graphe métier est autoritatif dans PostgreSQL (nœuds, relations, provenance, visibilité, statut observé, importé, déduit, proposé par IA, vérifié). Les algorithmes (voisins, chemins bornés, communautés, motifs, filtrage temporel) tournent dans le backend avec NetworkX (BSD-3-Clause), sans nouvelle base de graphes. Cognee n'apporte que l'enrichissement sémantique, par le Control Plane ; Qdrant ne sert qu'à la similarité documentaire. Aucune relation entre tenants, et une relation indirecte n'est jamais présentée comme une preuve.

8. Preuves et chaîne de conservation

Le coffre des preuves du Compliance & Audit Agent n'existe pas encore dans le dépôt (développement parallèle). Le FAI définit une interface unique de coffre : original jamais modifié, empreinte, scellé et legal hold par /v1/evidence/*, registre de conservation chaîné propre au FAI sur le modèle de eai/domains/soc/evidence.py, annotations séparées, WORM seulement si le profil de stockage le déclare et le vérifie. Après fusion, l'interface est rebranchée sur le coffre du C&A sans réécrire les données déjà scellées. Un hash seul n'est jamais présenté comme une conservation probatoire complète.

9. Décisions humaines et actions

• Aucune mesure restrictive automatique (blocage de compte, gel de paiement, refus d'indemnisation, suspension de remboursement) hors d'un cadre préapprouvé par le client ; chaque action sensible passe par OPA avant tout effet, par un approbateur habilité distinct de l'enquêteur, puis par l'API autorisée du système métier, et son résultat est vérifié.
• Les enquêtes sur des salariés suivent les procédures RH et la confidentialité du client : accès restreint par OpenFGA, décision par les rôles RH désignés.

10. Sécurité et observabilité

• Contrôles en fail-closed : OpenFGA, OPA (eai.fraud), analyse des fichiers, quotas. Contenu non fiable (documents, résultats d'outils, mémoire) traité comme donnée, avec détection d'injection.
• OpenTelemetry de l'ingestion à la décision humaine, traces Opik pour les exécutions d'agents seulement (pas pour le scoring déterministe), métriques Prometheus sans identifiant client en label, journaux vers Alloy et OpenSearch.
• Grafana, Loki et Tempo sont sous AGPL-3.0 et refusés par l'ADR-0101 : Prometheus, Alertmanager, Alloy, OpenSearch, Jaeger, Opik et ClickHouse les remplacent.
• Le SOC Navin distingue les incidents de cybersécurité des alertes de fraude.

11. Rapports

PDF par ReportLab 5.1.0 (BSD-3-Clause), DOCX par python-docx 1.2.0 (MIT), XLSX par openpyxl 3.1.5 (MIT), CSV et JSON par la bibliothèque standard ; le Control Plane n'a pas de service de rendu (audit, section 6). Les rapports séparent observations, inférences et conclusions humaines validées ; un rapport final n'est jamais modifié, il est amendé.

12. Vérité des capacités

Aucun connecteur n'est déclaré opérationnel sans test réel ou sur un environnement de test représentatif. Aucun taux de fraude détectée n'est publié sans vérité terrain fiable. Les limites sont écrites dans navin-fraud-investigation/docs/KNOWN_LIMITATIONS.md.

Décisions de l'utilisateur

Le 2026-11-04, l'utilisateur a tranché les choix ouverts :

1. Pile ML : scikit-learn, XGBoost et SHAP dès le départ (option « c », préférée à l'option recommandée scikit-learn seul). XGBoost est livré par xgboost-cpu pour rester sous Apache-2.0.
2. Artefacts de modèles : stockage objet du Control Plane, empreinte SHA-256, signature Ed25519 dont la clé est dans OpenBao, registre des versions dans le schéma fraud.
3. Preuves : scellés et legal holds du Control Plane et chaîne de conservation du FAI, convergence avec le coffre du C&A après fusion.
4. Guidia : hors de ce dépôt, sans impact sur le FAI pour l'instant ; le point reste ouvert.

Points à valider par le client

1. Remplacement de Grafana, Loki et Tempo (AGPL-3.0) par les composants autorisés du catalogue, comme pour l'ADR-0175.
2. Liste des actions restrictives préapprouvées par secteur (par défaut : aucune).
3. Procédure RH applicable aux enquêtes sur des salariés et rôles qui l'appliquent.
4. Emplacement de l'écosystème Guidia.

Alternatives écartées

• LLM comme moteur de scoring ou d'écriture de règles de production : non déterministe, non auditable.
• Langage de règles par expressions Python ou SQL fourni par l'utilisateur : exécution de code arbitraire.
• Base de graphes dédiée (Neo4j, sous GPL ou commercial) ou Cognee comme graphe métier : seconde source de vérité.
• Nouveau broker (Kafka, RabbitMQ) : le courtier et la file durable existants suffisent.
• Paquet xgboost : dépendance nvidia-nccl-cu13 sous licence propriétaire.
• Extension du registre /v1/models ou du Hub pour les modèles tabulaires : changement de contrats partagés.
• Attendre le coffre du C&A : bloquerait les lots preuves, dossiers, revue humaine et packs.
• LLaMA-Factory : aucun affinage de modèle de langage n'est nécessaire.

Plan de réalisation

Quinze lots suivis sur le tableau du projet (tâches « FAI ») : audit et architecture ; fondations du backend ; ingestion et connecteurs ; règles ; features, modèles et scoring ; corrélation et alertes ; graphe et documents ; dossiers, preuves et décisions ; RAG et mémoire ; sous-agents et copilote ; packs ; gouvernance, rapports et KPI ; écrans ; observabilité et sécurité ; cycle de vie, scénarios de bout en bout et préparation production.