89 lines
4.4 KiB
Markdown
89 lines
4.4 KiB
Markdown
# Business-QA – Interfaces et API
|
||
|
||
Module d’anonymisation, interrogation IA métier et recontextualisation pour les dossiers notaires dans `ai_working_help`.
|
||
|
||
## Rôle
|
||
|
||
1. **Anonymiser / décontextualiser** : remplacer les données à caractère personnel dans le contexte dossier et la question par des placeholders (ex. `PII_0`, `PII_1`), avec conservation d’un mapping pour la restitution.
|
||
2. **Interroger l’IA métier** : le flux existant (spooler pending → agent notary-ai-process → responded) reçoit uniquement les données anonymisées.
|
||
3. **Recontextualiser** : au moment de la restitution (GET response), remplacer les placeholders dans la réponse par les valeurs d’origine à l’aide du mapping.
|
||
|
||
## Structure du module
|
||
|
||
```
|
||
business-qa/
|
||
config/
|
||
default.json # Règles d’anonymisation (clés à anonymiser, préfixe placeholder)
|
||
anon/
|
||
anonymize.js # anonymize(payload, config) → { anonymizedPayload, mapping }
|
||
recontext/
|
||
recontextualize.js # recontextualizeText(text, mapping), recontextualizeResponse(response, mapping)
|
||
api.js # Route Express montée en /v1/business-qa
|
||
interfaces.md # Ce fichier
|
||
example/
|
||
index.html # Page d’exemple
|
||
```
|
||
|
||
## Configuration (config/default.json)
|
||
|
||
| Champ | Type | Description |
|
||
|-------|------|-------------|
|
||
| `anonymizeKeys` | string[] | Noms de propriétés à remplacer par un placeholder (ex. firstName, lastName, email, address). |
|
||
| `placeholderPrefix` | string | Préfixe des placeholders générés (ex. "PII" → PII_0, PII_1). |
|
||
| `recursive` | boolean | Si true, parcours récursif des objets imbriqués. |
|
||
| `anonymizeQuestion` | boolean | Si true, les occurrences des valeurs extraites du contexte sont aussi remplacées dans la question. |
|
||
|
||
Fichiers additionnels dans `config/` (ex. `custom.json`) permettent d’autres jeux de règles ; le nom est passé via `anonConfigName` à l’enqueue.
|
||
|
||
## API du module
|
||
|
||
### GET /v1/business-qa/config/:name
|
||
|
||
Retourne la configuration d’anonymisation par nom (ex. `default` → `config/default.json`).
|
||
|
||
- **Réponse 200** : `{ ...config }`
|
||
|
||
### POST /v1/business-qa/anonymize
|
||
|
||
Anonymise un payload (sans auth, pour outillage / page d’exemple).
|
||
|
||
- **Body** : `{ payload: object, config?: object, configName?: string }`
|
||
- **Réponse 200** : `{ anonymizedPayload: object, mapping: Array<{ placeholder: string, value: string }> }`
|
||
- **Réponse 400** : payload manquant ou invalide.
|
||
|
||
### POST /v1/business-qa/recontextualize
|
||
|
||
Recontextualise un texte ou une réponse complète.
|
||
|
||
- **Body** : `{ mapping: Array<{ placeholder, value }>, response?: object }` ou `{ mapping, text?: string }`
|
||
- **Réponse 200** : `{ response?: object }` ou `{ text?: string }`
|
||
- **Réponse 400** : mapping manquant ou ni `response` ni `text` fourni.
|
||
|
||
### Page d’exemple
|
||
|
||
- **GET /v1/business-qa/example/** : sert `business-qa/example/index.html`.
|
||
|
||
## Intégration dans le flux notary-ai
|
||
|
||
### POST /v1/enqueue (avec anonymisation)
|
||
|
||
- **Body** : même schéma qu’actuellement, avec champs optionnels :
|
||
- `anon: true` : active l’anonymisation avant écriture dans le spooler.
|
||
- `anonConfigName?: string` : nom de la config (défaut `"default"`).
|
||
- Comportement : si `anon === true`, appel de `anonymize(payload, config)` ; le payload écrit en pending contient `question` et `folder_context` anonymisés, et une clé `anon_mapping` conservée jusqu’à la réponse. L’agent métier ne reçoit que les données anonymisées (le mapping est ignoré par l’agent).
|
||
|
||
### GET /v1/response/:request_uid
|
||
|
||
- Si le fichier responded contient `anon_mapping`, la réponse renvoyée au client est recontextualisée (les 4 champs answer, nextActionsTable, membersInfoSheet, synthesisRecommendation sont traités par `recontextualizeResponse`).
|
||
|
||
## Contrats (types)
|
||
|
||
- **Mapping** : `Array<{ placeholder: string, value: string }>`.
|
||
- **Payload enqueue** : `{ request_uid, folder_uid?, office_uid?, user_id?, question, folder_context?, anon?, anonConfigName? }`.
|
||
- **Response** : `{ answer?, nextActionsTable?, membersInfoSheet?, synthesisRecommendation? }`.
|
||
|
||
## Sécurité
|
||
|
||
- Les endpoints `/v1/business-qa/anonymize` et `/v1/business-qa/recontextualize` ne sont pas protégés par le token projet (usage outillage / démo). Ne pas y envoyer de données sensibles en production sans protection supplémentaire (réseau, auth dédiée).
|
||
- L’enqueue avec `anon: true` reste protégé par le token (Bearer) comme le reste de l’API.
|