# Notary AI – API et spooler (ai_working_help)

## Rôle

**ai_working_help** est une API d’écoute qui tourne sur la **machine où Cursor et la boucle d’agents** sont utilisés (pas sur le serveur où l’app est déployée). L’application déployée appelle cette API (NOTARY_AI_AGENT_URL) pour enqueuer les questions et récupérer les réponses ; les réponses sont produites par les agents Cursor (notary-ai-loop + notary-ai-process) qui lisent/écrivent le spooler sur ce PC.

## Rôle métier et format de réponse (côté agent)

- **Utilisateurs autorisés** : strictement le notaire connecté et les collaborateurs (mêmes droits que le notaire). Les invités et les tiers ne peuvent pas utiliser le chat IA.
- **Périmètre** : l'agent répond **uniquement** sur le **dossier en cours** et les **documents fournis**. Il peut lire en base et consulter strictement le dossier concerné et les documents du dossier.
- **Spécialisation** : droit, et plus encore les activités notariales. Réponses spécifiques au type de dossier et aux documents fournis.
- **Interdiction** : ne jamais communiquer de RIB ni de coordonnées transactionnelles.

**Format de réponse (4 champs)** renvoyés par l'API dans `response` :

| Champ | Contenu |
|-------|--------|
| **answer** | Réponse textuelle directe à la question posée. |
| **nextActionsTable** | Tableau des prochaines actions à mener sur le dossier pour ce type de dossier : documents à fournir / demander / faire valider aux membres du dossier, et de manière générale pour ce type de dossier à l'extérieur. |
| **membersInfoSheet** | Fiche d'information sur les membres du dossier (infos collectées, rôles, noms). |
| **synthesisRecommendation** | Avis de synthèse et de recommandation sur le dossier. |

## Id projet et résolution

- **Côté API** : le token est trouvé en parcourant tous les projets et tous les envs comme décrit précédemment : pour chaque `projects/<id>/.secrets/<env>/ia_token`, on compare le Bearer au contenu du fichier ou à (contenu + env). La première correspondance donne l'id projet et l'env (test, pprod, prod, etc.).
- **Côté scripts** : id (et env) résolus **uniquement** par **MAIL_TO** (adresse « to » des mails) ou **AI_AGENT_TOKEN** (lit `.secrets/<env>/ia_token`). Pas de fallback. Voir `projects/README.md`.
- Données par projet : `projects/<id>/data/notary-ai/` (pending/, responded/).

## API (serveur Node)

- **POST /v1/enqueue**  
  Body : `{ request_uid, folder_uid, office_uid, user_id, question, folder_context }`.  
  Réponse **202** : `{ request_uid }`.  
  Écrit dans `projects/<id>/data/notary-ai/pending/<safe_uid>.json`. **Authentification** : header `Authorization: Bearer <token>` obligatoire (le token identifie le projet) ; 401 si absent ou inconnu.

- **GET /v1/response/:request_uid**  
  Réponse **200** : `{ status: "pending" }` ou `{ status: "responded", response: { answer, nextActionsTable, membersInfoSheet, synthesisRecommendation } }`.  
  Lit d’abord `projects/<id>/data/notary-ai/responded/`, sinon `pending/`. **Authentification** : idem (token obligatoire).

- **GET /v1/health** et **GET /health** : santé du service (sans authentification).

Lancement : depuis la racine de ia_dev : `node ai_working_help/server.js`. Port par défaut : **3020** (`AI_WORKING_HELP_PORT`).

## Configuration côté application déployée

- **NOTARY_AI_AGENT_URL** : URL de base sans segment projet dans le chemin, sans slash final, ex. : `http://192.168.1.173:3020/v1`. Le backend ajoute `/enqueue` et `/response/:request_uid`.
- **NOTARY_AI_AGENT_TOKEN** : le token envoyé par l’app est de la forme **base** + **env**. **env** est le nom d’environnement (test, pprod, prod), à modifier selon les environnements. Côté ia_dev, ce token est trouvé en parcourant tous les projets et tous les envs (fichiers `projects/<id>/.secrets/<env>/ia_token`) ; le fichier peut contenir le token complet (ex. `nicolecoffreiotest`) ou la base seule (ex. `nicolecoffreio`), le serveur comparant alors le Bearer à `contenu_du_fichier + env`.

## Scripts (depuis la racine de ia_dev, MAIL_TO ou AI_AGENT_TOKEN défini)

- **./ai_working_help/notary-ai/list-pending-notary-ai.sh** : liste les fichiers `projects/<id>/data/notary-ai/pending/*.json` (id résolu par MAIL_TO ou AI_AGENT_TOKEN).
- **./ai_working_help/notary-ai/write-response-notary-ai.sh** : écrit la réponse dans responded/, supprime le pending.  
  Options : `--pending-path <path> --response-json <json>` ou `--request-uid <uid> --answer "..." [--next-actions-table "..." ] [--members-info-sheet "..."] [--synthesis-recommendation "..."]`.

## Agents Cursor

- **notary-ai-loop** (`.cursor/agents/notary-ai-loop.md`) : orchestre la boucle (liste pending, lance notary-ai-process ; x cycles ou une fois).
- **notary-ai-process** (`.cursor/agents/notary-ai-process.md`) : pour chaque pending, produit les 4 champs et appelle write-response-notary-ai.sh.

Les agents sont dans **.cursor/agents/**. À invoquer depuis la racine de ia_dev ; les scripts s'exécutent depuis la racine de ia_dev.