Aller au contenu principal

ADR-0182 : Navin Enterprise Agent Souscription et Évaluation des Risques, couche produit d'assurance au-dessus du Control Plane

  • Statut : proposé le 2026-11-04, en attente de validation de l'utilisateur (voir « Points à valider »)
  • Date : 2026-11-04
  • Portée : nouveau projet navin-enterprise-assurance-souscription/ (backend FastAPI navin_souscription, workers, intégration Navin, pas de frontend propre : le socle frontend partagé de l'ADR-0180 porte l'interface), types additifs du modèle OpenFGA (deploy/policies/openfga/model.fga, type souscription_instance et objets), paquet OPA eai.assurance_souscription (deploy/policies/opa/assurance_souscription.rego), contrats contracts/v1/assurance-souscription-action-request.schema.json et contracts/v1/assurance-souscription-copilot-event.schema.json, gabarit d'agent du Navin Manager préparé mais non publié (navin-assurance-souscription-agent)
  • Documents liés : ADR-0101 (politique de licences), ADR-0103 (vLLM et LiteLLM), ADR-0108 (Opik), ADR-0166 (ClamAV et YARA-X), ADR-0173 (séparation du Manager et d'Enterprise), ADR-0174 (mémoire Mem0 et Cognee), ADR-0175 (Navin Enterprise RAG Agent), ADR-0176 (Banking Back-Office, implémentation de référence dont les modules génériques sont copiés), ADR-0180 (socle frontend des agents sectoriels), décision du 2026-11-04 (.navin/continuity/DECISIONS.md, un seul frontend, backend dérivé par copie), cahier des charges agent_uses_cases/02_Assurance_Souscription_Evaluation_Risques.md

Contexte​

Le client demande un agent de souscription et d'évaluation des risques pour un assureur ou un courtier : prise en charge des demandes de devis et d'affaires nouvelles, questionnaire de risque conditionnel et collecte de données, éligibilité par règles versionnées, indicateurs de risque explicables, contrôles d'accumulation et de capacité, propositions tarifaires en Decimal par devise sous une version de tarif datée, revue des documents médicaux ou techniques, référé vers un souscripteur humain, décision enregistrée par un humain avec maker-checker selon la matrice d'autorité, et demande d'émission vers le système d'administration des polices, source de vérité du contrat.

L'audit du 2026-11-04 (navin-enterprise-assurance-souscription/docs/NAVIN_INTEGRATION_AUDIT.md) confirme que le Control Plane fournit déjà l'identité et le contexte tenant et projet, l'évaluation des politiques OPA, OpenFGA, les approbations avec séparation des tâches, l'analyse obligatoire des fichiers (quarantaine, ClamAV, YARA-X, Docling), les bases de connaissances, la mémoire, les connecteurs avec courtier de secrets, l'outbox transactionnelle, les traces OpenTelemetry et Opik, les métriques Prometheus et l'audit chaîné. Le produit UC-00 (ADR-0176) fournit une couche produit complète dont les modules génériques (configuration, erreurs, i18n, autorisations, audit, travaux, worker, client du Control Plane, session RLS, Action Gateway, connecteurs, observabilité, pipeline documentaire, copilote, opérations) sont indépendants du métier bancaire.

Il manque tout le métier de souscription : aucun dossier, aucun questionnaire, aucun moteur d'éligibilité, aucun indicateur de risque, aucune tarification, aucune matrice d'autorité par somme assurée et complexité, aucune demande d'émission vers une administration des polices.

Décision​

1. Une couche produit, dérivée par copie du produit de référence​

Le produit est un backend FastAPI (navin_souscription, port de développement 8473, Redis 6394, préfixe /api/v1/assurance-souscription) qui ne réimplémente rien de la plateforme : il appelle le Control Plane par le SDK enterprise_ai. Les modules génériques de navin_backoffice sont copiés à l'identique (hormis le nom du paquet, le schéma PostgreSQL souscription et les identifiants d'actions) ; ils ne sont pas partagés en bibliothèque pour que chaque produit reste livrable et versionnable seul (décision du 2026-11-04). Aucun frontend n'est écrit : l'ADR-0180 porte l'interface de tous les agents sectoriels à partir du product.manifest.json.

2. Le système d'administration des polices reste la seule source de vérité​

Le produit ne crée jamais une police. Une demande d'émission (issuance_handoffs) passe par l'Action Gateway, est envoyée au connecteur policy_administration et reste unknown_pending_confirmation tant que la source n'a pas renvoyé une référence et une version de police ; source_confirmed est une contrainte CHECK qui exige ces deux valeurs. Le bac à sable déterministe des connecteurs est nommé comme tel dans chaque réponse (sandbox: true) et ne se présente jamais comme une confirmation de la source.

3. Les scores sont des indicateurs, les décisions sont humaines​

Le moteur d'indicateurs (risk_assessments) calcule à partir de facteurs versionnés (underwriting_rulesets de type risk_indicators) un score, une bande de probabilité et une perte attendue gardés comme valeurs distinctes, chacune avec sa méthode, son incertitude et la liste des facteurs inconnus. Aucune ligne de underwriting_decisions n'est écrite par un moteur ni par le LLM : la décision (accept, request_information, modify, decline, refer) est enregistrée par un souscripteur humain à travers l'Action Gateway ; le dépassement de délégation est préparé comme un référé au senior, jamais comme une acceptation (règle OPA authority_insufficient_for_decision). Le moteur d'éligibilité route (eligible, needs_information, refer, out_of_appetite_proposed) et ne refuse jamais définitivement.

4. Action Gateway et matrice de délégation​

Le paquet OPA eai.assurance_souscription décide par type d'opération (acceptation, refus, modification, référé, proposition de conditions, demande de tarif, demande d'émission, délégation, changement de règle, export), montant (somme assurée ou prime, chaîne Decimal comparée numériquement) dans une seule devise, branche, région, complexité, conflit d'intérêts, niveau d'autorité et délégations datées révocables. Il expose decision.applies (vrai pour les actions souscription.* et document.* seulement) ; l'approbateur n'est jamais l'initiateur ni un agent ni un service ; une complexité critical exige deux approbations.

5. Tarification en Decimal sous une version de tarif datée​

Une proposition de prime (pricing_quotes) est calculée en Decimal à partir d'une version de tarif active et datée (underwriting_rulesets de type tariff) et d'un instantané figé des caractéristiques tarifantes ; les étapes (base, majorations, taxes) et la règle d'arrondi sont conservées ; un changement de caractéristique invalide la proposition. Jamais un taux lu en direct, jamais une somme entre devises, jamais un prix tiré du texte du LLM.

6. Règles versionnées, activées par un autre humain​

Éligibilité, facteurs d'indicateurs, matrice d'autorité, tarif, registre de la machine à états et questionnaire sont des données versionnées (underwriting_rulesets) : un brouillon est activé par un humain autre que son auteur (CHECK activated_by_another_human, OPA rule_activator_is_author, OpenFGA can_activate ... but not author) ; une version active n'est jamais modifiée.

7. Machine à états versionnée​

Les statuts du dossier et les transitions permises (section 6 du cahier des charges) sont un registre versionné (state_machine_version sur chaque dossier et chaque transition) ; toute transition est appliquée côté serveur avec expected_version, et les transitions accept, decline, issue et confirm_issuance ne sont pas des transitions libres mais le résultat d'une décision humaine ou d'une confirmation de la source.

8. Documents, connaissances, mémoire, copilote​

Même pipeline documentaire que l'UC-00 (quarantaine, ClamAV, YARA-X, Docling, revue humaine quand l'extraction est ambiguë, le téléverseur ne relit jamais). Une contradiction entre le questionnaire et un rapport d'inspection crée un attribut contested qui garde les deux valeurs. Le copilote réutilise le runtime bancaire : outils typés read, prepare, side_effect, approbation d'un effet par un humain autre que le propriétaire de l'exécution, gouvernance DLP, événements au contrat assurance-souscription-copilot-event (même enveloppe que le bancaire).

9. Gabarit préparé, non publié​

Le Service Template navin-assurance-souscription-agent est un brouillon sous navin-integration/ et un registre navin-manager/agent-templates/*.yaml au statut prepared ; il n'est jamais écrit sous navin-manager/catalog.

Conséquences​

  • Un troisième produit assurance au-dessus du même Control Plane, avec le même socle technique que l'UC-00 : la dette de duplication est assumée et documentée (une correction d'un module générique doit être reportée dans chaque copie).
  • Les engagements de non-automatisation (le LLM n'accepte, ne refuse, ne tarife ni n'émet) sont portés par la base de données, OPA et OpenFGA, pas seulement par les prompts.
  • Les connecteurs réels (administration des polices, moteur de tarification, historique sinistres, capacité) sont des contrats de capacité ; sans connecteur configuré, le contrôle d'accumulation est not_performed et l'émission reste prepared.

Points à valider​

  1. La matrice d'autorité de démonstration (paliers 250 000, 2 500 000, 25 000 000 EUR et équivalents) remplace-t-elle une matrice client ? Elle est une donnée versionnée par instance.
  2. Le choix de ne pas partager les modules génériques en bibliothèque (copie assumée) est-il maintenu pour les cinq produits assurance ?
  3. Les lignes de métier et les régions permises par défaut dans deploy/policies/opa/data.json.

Alternatives écartées​

  • Un score qui accepte ou refuse automatiquement sous un seuil : refusé, incompatible avec la section 7.4 du cahier des charges et avec les obligations d'explicabilité.
  • Un tarif lu en direct depuis un moteur externe au moment du devis : refusé, non reproductible ; la version datée est conservée avec la proposition.
  • Une bibliothèque Python partagée des modules génériques : écartée pour l'instant (décision du 2026-11-04).

Plan de réalisation​

Audit et ADR, contrats et politiques, fondation backend (migration 0001 avec RLS, outbox, audit), modules métier (dossiers, preuves de risque, éligibilité, indicateurs, expositions, tarification), machine à états et décision maker-checker, documents et ingestion, copilote et outils, tests de sécurité et de résilience, six scénarios de recette par l'API réelle, manifeste produit et gabarit, documentation fr/en.