Brouillon dans LibreDesk : design et plan

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
maximeandClaude Opus 5.5 committed 2026-11-11 14:04:27 +01:00
1 parent fe884d82ba
commit a8ef0d8f6e
2 files changed
+555

No files matched your search

@@ -0,0 +1,128 @@
# Design : le brouillon de réponse, uniquement dans LibreDesk
Date : 2026-11-11. Issu d'un brainstorming entre Maxime et Claude, après lecture du code de LibreDesk v2.9.0 et de la configuration de la production (`helpdesk.sensima.ch`), en lecture seule.
## 1. L'intention
Aujourd'hui, un programme Python lancé par Gitea Actions lit LibreDesk, fait travailler les agents support et analyste, et dépose une proposition de réponse en note privée (`README.md`, `docs/spec.md`). Maxime veut essayer d'obtenir l'essentiel **avec LibreDesk seul** : pas de programme à côté, pas de modification du code de LibreDesk.
LibreDesk 2.9 sait déjà le faire nativement : le bouton **« Générer une réponse »** de la zone de saisie rédige un brouillon à partir de la base de connaissances (le métier) et de l'historique du client (ses autres conversations), et le met dans l'éditeur. Le travail est donc de **configurer** LibreDesk et de **remplir** sa base de connaissances, pas de programmer.
## 2. Ce que l'utilisateur vit
Un membre du support ouvre une conversation, clique sur « Générer une réponse » (en tapant éventuellement une consigne : « demande le numéro de station », « refuse poliment »). Le brouillon apparaît dans l'éditeur, appuyé sur la FAQ, le manuel, le savoir métier et les échanges passés avec ce client. Il le relit, le corrige, l'envoie lui-même. Il peut aussi interroger le panneau copilot (résumé, prochaine étape, historique du client, brouillon à insérer).
## 3. Objectifs, non-objectifs, anti-objectifs
**Objectifs**
- Un brouillon utile en un clic pour les demandes courantes, fondé sur les connaissances AIMsight et l'historique du client.
- Tout dans LibreDesk : configuration et contenu, rien d'autre à faire tourner (sauf le modèle d'embeddings, §5).
**Non-objectifs (décidés)**
- Pas de brouillon préparé automatiquement à l'arrivée du mail : le clic suffit (décision de Maxime).
- Pas de diagnostic chiffré sur les données de mesure (détecteurs, courbes, images de la caméra) : impossible dans LibreDesk seul.
- Pas de modification du code source de LibreDesk (décision de Maxime).
- Pas de règles d'automatisation pour l'instant : à voir plus tard (décision de Maxime : « on verra par la suite »).
**Anti-objectifs : ce qui serait un échec même si ça marche**
- **Un message qui part chez un client sans qu'un humain l'ait relu et envoyé.** Décision de Maxime : « toujours une relecture humaine avant envoi ». C'est la règle qui prime sur tout le reste.
- Des connaissances internes (seuils provisoires, notes de chantier, documents de projet d'un client) qui se retrouvent dans un brouillon.
- Une recherche métier qui dépend de l'ordinateur de Maxime en production.
## 4. Ce que LibreDesk 2.9 offre (vérifié dans le code)
- `POST /api/v1/ai/generate-reply` : brouillon par la boucle agentique ; outils toujours attachés : `search_articles` (base de connaissances, si un modèle d'embeddings est configuré) et l'historique du contact (`list_contact_conversations`, `fetch_conversation`). Le prompt système dit explicitement qu'un humain relira et enverra. Rien n'est envoyé : le texte revient à l'éditeur (`cmd/ai.go`, `internal/ai/copilot.go`).
- Copilot (panneau latéral), résumé en note privée, suggestion d'étiquettes (proposées, jamais posées).
- Instructions communes : Admin → IA → Providers → *Custom instructions*, ajoutées au prompt système (`internal/ai/agent.go`).
- Base de connaissances : extraits (*snippets*, privés, lus par l'IA seulement), import d'URL, centre d'aide (public), suggestions apprises des conversations résolues (désactivées).
- La recherche dans la base exige un modèle d'embeddings au format OpenAI (`POST <base_url>/embeddings`, avec le champ `dimensions` si on le règle).
- Le brouillon et `fetch_conversation` ne voient que les messages publics : les notes privées (dont celles du programme Python) n'entrent pas dans le brouillon.
- Les vecteurs sont stockés quelle que soit leur dimension (bge-m3 : 1024) ; la recherche couvre les extraits et les articles du centre d'aide.
- Garde SSRF désactivée par défaut (`[ssrf] enabled = false`) : LibreDesk peut joindre un modèle sur le réseau interne.
- Les **assistants** répondent eux-mêmes au client (par mail aussi, `internal/aiagent/worker.go`), sans mode brouillon : **exclus** par l'anti-objectif.
**État de la production le 2026-11-11** : complétion branchée sur Claude Sonnet 5.5 (`base_url` `https://api.anthropic.com/v1`, fournisseur « openai », `max_tokens` 1024, effort `medium`, instructions vides) ; **aucun modèle d'embeddings** ; base de connaissances vide ; un assistant `support_assistant` activé, sans instructions ni outils, auquel aucune règle n'envoie de conversation ; aucune règle d'automatisation ; aucun webhook ; aucun outil HTTP. Une seule boîte : « support AIMsight », canal mail.
## 5. Les décisions
### Décidées par Maxime
1. Uniquement les fonctions natives de LibreDesk ; pas de modification de son code.
2. Le brouillon au clic suffit.
3. Toujours une relecture humaine avant envoi.
4. Modèle d'embeddings **hébergé chez nous**. D'abord un essai avec **LM Studio sur le poste de Maxime**, branché à l'**instance de test**, puis migration vers **Ollama** sur un serveur de l'entreprise pour la production.
5. Le tri des connaissances du §6 est validé ; les guides de lecture et les incidents sont remis à plus tard, une fois réécrits.
6. Les automatisations sont remises à plus tard.
7. La production et le futur serveur Ollama sont sur le même réseau.
### Choix de Claude (à relire)
- **Modèle d'embeddings : bge-m3** (multilingue : les clients écrivent en français et en allemand, la doc est en anglais). Même modèle sous LM Studio et sous Ollama ; réindexation complète après la migration (LibreDesk sait réindexer, et signale les vecteurs de dimension différente).
- **Extraits privés, pas le centre d'aide** : le centre d'aide est public.
- **Un extrait par unité de sens** : une question de la FAQ, une section du manuel, un incident, un document métier court. Titre explicite, source indiquée dans le texte.
- **Contenu en langue d'origine** (la FAQ et le manuel restent en anglais).
- **Import par un petit script ponctuel** qui appelle l'API de LibreDesk (`POST /api/v1/ai/snippets`), versionné dans ce dépôt, rejouable sur l'instance de test puis sur la production. Ce n'est pas du code de LibreDesk.
- **Désactiver `support_assistant`** : il ne fait rien aujourd'hui, mais répondrait aux clients dès qu'une règle lui confierait une conversation.
- **Relever `max_tokens`** (1024 coupe les longues réponses et laisse peu de place aux appels d'outils) : valeur à fixer pendant l'essai, de l'ordre de 4096.
- **Le programme Python sur Gitea reste tel quel** : ce design n'y touche pas ; le garder, le mettre en pause ou le retirer est une décision à part.
- **Chaque modification de la production est présentée à Maxime et faite seulement avec son accord.**
- **Si la complétion par l'endpoint Anthropic échoue pendant l'essai** (appels d'outils, effort de raisonnement), on essaie d'abord sans effort de raisonnement ; si les outils ne marchent toujours pas, **on s'arrête et Maxime choisit** la suite (autre fournisseur au format OpenAI, modèle local, intermédiaire de traduction, ou abandon). Aucune de ces options n'est prise sans lui : chacune change soit la protection des données, soit la règle « rien d'autre à faire tourner ».
- **L'import des extraits demande une clé d'administrateur** (les routes `/api/v1/ai/snippets` exigent `ai:manage`), pas la clé de l'agent « Agent IA ». Sur l'instance de test, l'utilisateur `System` ; en production, une clé créée pour l'occasion et révoquée après.
## 6. Le contenu de la base de connaissances
Sources : `~/Support-Agent` (plus complet) et `agents/knowledge/` de ce dépôt.
**À verser (extraits privés)**
1. **FAQ AIMsight** (`Support-Agent/docs/aimsight/AIMsight FAQ.pdf`, rév. 1.5, ~50 questions) : un extrait par question.
2. **Manuel de la station** (`Support-Agent/docs/aimsight/AIMsight Test Manual.pdf`, « AIMsight Station Guide », rév. 1.5, 23 p.) : un extrait par section. Exclure la partie *Safety and Regulatory Information* si elle n'aide pas à répondre (choix du constructeur).
3. **Savoir métier général** : `Support-Agent/docs/domaine/` (ce que mesure la station, pièges des données), `docs/displacement/domaine/ce-que-regarde-le-client.md`, `docs/energy/domaine/` (sauf les cas annotés), `labeling/connaissances/` (chaîne de mesure, cycle thermique, images de la caméra, trous, métriques de qualité, colonnes des déplacements ; sauf `cas-annotes-par-l-expert.md` et `incident-de-barcelone.md`), et `agents/knowledge/analyste/familles.md` de ce dépôt (familles d'événements). Avant l'import, retirer de ces textes les noms de stations, de lieux et de clients, les commandes d'outils et les seuils provisoires (choix de Claude, dans la ligne de la décision ci-dessous).
**Plus tard, une fois réécrits (décision de Maxime : hors de la première version)**
- Les **guides de lecture** (`Support-Agent/docs/{energy,cellular,storage,temperature}/guide/`) : marqués « brouillon », seuils provisoires, partie 2 destinée à l'ingénieur support.
- Les **incidents validés par l'expert** (`Support-Agent/events/E-0xx/event.md`, 14 fiches) et les **cas annotés** : écrits pour l'agent analyste, avec commandes, chiffres internes, noms de stations et de lieux.
**À mettre dans les instructions communes**
- Les règles de rédaction de `agents/knowledge/support/redaction.md`, réduites à ce qui vaut pour un mail : la réponse d'abord (oui, non, ou on ne peut pas le dire, et pourquoi), dans la langue du client, rien d'interne, honnête sur ce qui n'est pas établi, phrases simples. Sans ce qui concerne `analyse.md`, le PDF ou Typst.
**À laisser de côté**
- Le chantier : `docs/decisions.md`, plans, `vues-deplacements/contexte/`, séances des learners, seuils provisoires, `questions-pour-l-expert.md`, `point-de-depart.md`.
- Les prompts et outils des agents : `regles-de-preuve.md`, `lire-les-donnees.md`, `modele.typ`, `presentation.md`.
- Les PDF « Mur de soutènement GN-* » : documents de projet d'un client.
- Les rapports de situation déjà envoyés (`Support-Agent/support/`) : l'historique du client est déjà lu par l'outil natif.
Volume attendu : 70 à 90 extraits.
## 7. Les étapes
### Étape 1 : l'essai sur l'instance de test
L'instance de test (`instance-de-test/`, LibreDesk v2.9.0 et Mailpit, `docs/verifications.md`) tourne dans Docker sous WSL ; rien n'en sort.
1. LM Studio sur le poste de Maxime (Windows), serveur activé, bge-m3 chargé.
2. Vérifier que le conteneur LibreDesk joint LM Studio sur l'hôte Windows (adresse selon le mode réseau de WSL et de Docker).
3. Configurer l'instance de test : complétion (Claude, comme en production, avec une clé de test), embeddings (LM Studio), instructions communes, `max_tokens`.
4. Importer la base de connaissances avec le script.
5. Créer des conversations de test à partir de mails représentatifs (`instance-de-test/mail-exemple.txt` et quelques cas réels anonymisés) et un contact avec plusieurs conversations, pour l'historique.
6. Générer des brouillons et les juger avec Maxime.
Points à vérifier pendant l'essai : LibreDesk et LM Studio s'entendent sur le format des embeddings (champ `dimensions`) ; la complétion par l'endpoint Anthropic au format OpenAI fonctionne avec les appels d'outils et l'effort de raisonnement (jamais testée, même en production) ; la recherche ramène les bons extraits en français et en allemand ; la longueur maximale suffit.
### Étape 2 : la production
Une fois l'essai jugé bon par Maxime :
1. Ollama et bge-m3 sur un serveur de l'entreprise, à faire par la personne qui gère le serveur. D'après Maxime, la production et ce serveur sont **sur le même réseau** : LibreDesk joint Ollama par une adresse interne, sans tunnel ni proxy. Ollama n'ayant pas d'authentification, son port ne doit pas être exposé hors du réseau interne.
2. Brancher les embeddings de la production sur Ollama.
3. Importer la base de connaissances, poser les instructions communes, relever `max_tokens`.
4. Désactiver `support_assistant`.
5. Vérifier sur une vraie conversation que « Générer une réponse » marche et que rien n'est envoyé.
Chaque point est présenté à Maxime avant d'être fait.
## 8. Ce qui compte pour juger le résultat
- Sur les demandes courantes, le brouillon est assez bon pour être envoyé après une relecture et des retouches légères.
- Il s'appuie sur la FAQ, le manuel ou un incident connu quand la question s'y prête, et sur les échanges passés avec le client.
- Il ne contient rien d'interne, n'invente ni procédure ni délai.
- Rien ne part sans un clic humain sur « Envoyer ».
## 9. Laissé au constructeur
- La conversion des PDF en texte et leur découpage (par question, par section).
- Le texte exact des instructions communes, à partir de `redaction.md`.
- Le choix des mails de test et leur anonymisation.
- La forme du script d'import (idempotent de préférence : rejouable sans doublons).
- La valeur finale de `max_tokens`.