Files

80 lines
5.5 KiB
Markdown
Raw Permalink Normal View History

# Support-AI : le diagnostic automatique des demandes de support
Les demandes des clients arrivent par mail dans LibreDesk. Quand une conversation porte l'étiquette `tri:diagnostic`, `python -m support_diagnostic.run` passe le mail aux agents support et analyste (copiés de `Support-Agent/API/`, dans `agents/`), puis dépose leur proposition de réponse **en note privée** dans la conversation. Un humain relit, corrige et envoie lui-même.
Spec : `docs/spec.md`. Vérifications de la phase 0 : `docs/verifications.md`. Plan de la phase 1 : `docs/plans/2026-11-09-phase-1.md`. Idées laissées de côté : `docs/pistes.md`.
2026-11-11 15:42:36 +01:00
## Le brouillon dans LibreDesk
L'autre voie, sans programme à côté : dans une conversation, le bouton **« Generate reply »** de LibreDesk rédige un brouillon dans l'éditeur, appuyé sur la base de connaissances (FAQ, manuel de la station, savoir métier) et sur les conversations précédentes du client. Rien n'est envoyé : un humain relit et clique lui-même sur « Send ». Le panneau « Juno » (copilot) répond aussi aux questions de l'agent sur la conversation.
- Le corpus de la base : `base_connaissances/corpus/` (un fichier par extrait, relu à la main) ; les instructions communes : `base_connaissances/instructions.md` (à coller dans Admin → IA → Providers → Custom instructions).
- Réimporter après une retouche (clé d'administrateur ; simulation sans `--ecrire` ; ne supprime jamais rien) : `LIBREDESK_URL=… LIBREDESK_ADMIN_KEY=… LIBREDESK_ADMIN_SECRET=… .venv/bin/python -m base_connaissances.importer --ecrire`.
- Spec : `docs/superpowers/specs/2026-11-11-libredesk-natif-design.md` ; plan : `docs/plans/2026-11-11-libredesk-natif.md` ; essai : `docs/verifications.md` ; mise en production : `docs/production-libredesk-natif.md`.
## Aucun mail ne part au client
Chaque barrière suffit seule :
1. Le compte LibreDesk « Agent IA » n'a pas la permission `messages:write` : LibreDesk refuse toute réponse au client (403).
2. Seul `support_diagnostic/libredesk.py` parle à LibreDesk, et il ne sait écrire qu'une note privée (`private: True` en dur, sans destinataire) et des étiquettes ; une réponse de LibreDesk qui n'est pas une note privée arrête toute l'exécution (`Garde`). `tests/test_garde_fou.py` le vérifie dans le code.
3. Les agents n'ont aucun accès à LibreDesk : ils rendent du texte.
4. Simulation par défaut : seul `DRY_RUN=false` écrit, et seulement avec une liste blanche.
5. `KILL_SWITCH` arrête tout avant la moindre lecture.
## Les étiquettes
| Étiquette | Posée par | Sens |
|---|---|---|
| `tri:diagnostic` | le tri (humain, règle LibreDesk…) | à diagnostiquer |
| `diag:en-cours` | ce dépôt | traitement en cours (un runner tué la laisse : la retirer à la main) |
| `diag:fait` | ce dépôt | note posée, avec une proposition de réponse |
| `diag:ignore` | ce dépôt | note posée, sans proposition (question des agents, mail sans texte) |
| `diag:erreur` | ce dépôt | échec ; une note courte le dit |
| `diag:relancer` | un humain | refaire le diagnostic ; ses notes privées servent alors de contexte aux agents |
Éligible : `tri:diagnostic` et (aucune `diag:*`, ou `diag:relancer`). Les six étiquettes doivent exister dans LibreDesk (un admin les crée).
## Réglages (Gitea : Settings → Actions)
| Nom | Type | Rôle |
|---|---|---|
| `LIBREDESK_URL` | variable | l'adresse de LibreDesk |
| `LIBREDESK_API_KEY`, `LIBREDESK_API_SECRET` | secrets | la clé de l'agent « Agent IA » |
| `ANTHROPIC_API_KEY` | secret | la clé de l'API Claude |
| `DRY_RUN` | variable | `false` pour écrire ; sinon simulation |
| `ALLOWED_CONVERSATION_IDS` | variable | uuid séparés par des virgules, ou `*` ; obligatoire pour écrire |
| `MAX_CONVERSATIONS_PER_RUN` | variable | défaut 3 |
| `KILL_SWITCH` | variable | non vide (autre que `false`, `0`) : rien ne tourne |
Le rôle « Agent IA » dans LibreDesk : `conversations:read`, `conversations:read_all`, `messages:read`, `messages:write_private`, `conversations:update_tags`, rien d'autre.
**Si le dépôt passe en privé** : l'étape « Récupérer le code » des workflows télécharge le code sans s'authentifier et échouerait. Avant de changer la visibilité, lui donner le jeton de l'exécution : `env: TOKEN: ${{ github.token }}`, et l'adresse `https://x-access-token:$TOKEN@${GITHUB_SERVER_URL#https://}/$GITHUB_REPOSITORY.git`.
Lancer : Actions → `support-diagnostic` → Run workflow (simulation par défaut ; une conversation précise en option : elle est traitée même sans `tri:diagnostic`, toujours sous la liste blanche). Un workflow lancé à la main doit être sur la branche par défaut.
## Sur le poste
```bash
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
```
```bash
.venv/bin/python -m unittest discover -s tests -v
```
L'instance LibreDesk de test (LibreDesk v2.9.0 et Mailpit, un piège SMTP : rien ne sort) : `docs/verifications.md`, section « L'instance de test ». La préparer, puis le test de bout en bout :
```bash
.venv/bin/python -I instance-de-test/preparer.py 'TestAdmin-2026!' instance-de-test/mail-exemple.txt
```
```bash
set -a && . instance-de-test/.env && set +a && LIBREDESK_TEST_URL=$LIBREDESK_URL .venv/bin/python -m unittest tests.test_instance -v
```
Un vrai diagnostic sur l'instance de test (coûte des crédits ; les données des stations sont celles de `Support-Agent`) :
```bash
set -a && . instance-de-test/.env && set +a && DRY_RUN=false ALLOWED_CONVERSATION_IDS=$CONVERSATION AIMSIGHT_DATA=$HOME/Support-Agent/data ANTHROPIC_API_KEY=... .venv/bin/python -m support_diagnostic.run
```