Base de connaissances reprise de Support-AI : corpus, import, instructions, tests

Ajoute aussi WEISSHORN et MISSISSIPPI au test du corpus, et un message clair quand LibreDesk est injoignable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
maximeandClaude Opus 5.5 committed 2026-11-12 09:19:25 +01:00
1 parent 3a6e693d6d
commit cce2e039ed
130 files changed
+2784

No files matched your search

@@ -0,0 +1,133 @@
# Design : Support-LibreDesk, le brouillon de réponse dans LibreDesk
Date : 2026-11-12. Issu d'un brainstorming entre Maxime et Claude, après lecture complète de `~/Support-AI` (tout ce qui touche à LibreDesk).
## 1. L'intention
Le support AIMsight reçoit les demandes des clients par mail dans LibreDesk (`helpdesk.sensima.ch`, v2.9.0, auto-hébergé). Depuis le 2026-11-11, le bouton **« Generate reply »** de LibreDesk rédige un brouillon dans l'éditeur, appuyé sur une base de connaissances de 118 extraits (FAQ, manuel de la station, savoir métier) et sur les échanges précédents du client. Un humain relit et envoie lui-même.
Tout cela a été construit dans `~/Support-AI`, à côté d'un premier projet abandonné (un programme Python lancé par Gitea Actions, qui faisait travailler des agents et posait une note privée). **Support-LibreDesk remplace complètement Support-AI** (décision de Maxime) : il ne garde que l'intégration avec LibreDesk, et y ajoute ce qui manque pour la production.
Ce qui manque : la recherche dans la base passe par un modèle d'**embeddings**, qui tourne aujourd'hui **provisoirement sur le PC de Maxime** (LM Studio, `text-embedding-bge-m3`, `http://10.0.2.140:1234/v1`, adresse attribuée par DHCP). Si le PC s'éteint, se met en veille ou change d'adresse, les brouillons continuent d'arriver **sans la base de connaissances, et rien ne le signale**. Ce dépôt installe **Ollama sur le serveur où tourne LibreDesk**, pour que la production ne dépende plus du poste de Maxime. C'était déjà la décision de Maxime dans le design précédent : LM Studio pour l'essai, Ollama pour la production.
Méthode voulue par Maxime : **tout simuler sur son ordinateur d'abord**, puis reproduire la même chose sur le vrai serveur.
## 2. Objectifs, non-objectifs, anti-objectifs
**Objectifs**
- Un dépôt autonome qui porte tout ce qu'il faut pour le brouillon dans LibreDesk : la base de connaissances et son import, les instructions communes, l'instance de test, Ollama, et le document de production.
- Une seule image Docker qui contient Ollama **et** bge-m3 déjà téléchargé : elle démarre sans rien aller chercher sur Internet, et c'est exactement le même modèle chez Maxime et sur le serveur.
- Tout éprouvé de bout en bout sur le poste de Maxime avant de toucher au serveur.
- Sur le serveur : une seule commande pour lancer Ollama, avec redémarrage automatique.
- Après le passage : LibreDesk en production utilise Ollama, les vecteurs des 118 extraits sont recalculés avec lui, le PC de Maxime et LM Studio ne servent plus.
- Les opérations courantes lancées d'un clic, par des **tâches VS Code** (idée de Maxime).
**Non-objectifs (décidés)**
- **Les fonctions initiales de Support-AI sont abandonnées** (décision de Maxime) : le diagnostic par les agents support et analyste, le programme `support_diagnostic`, les notes privées, les étiquettes `tri:*` / `diag:*`, le rôle « Agent IA », les workflows Gitea. Rien de cela n'est repris.
- **On ne recode pas LibreDesk** (décision de Maxime) : ni son code, ni son conteneur, ni son reverse proxy. Seulement sa configuration et son API.
- Pas d'alerte si Ollama ne répond plus : le redémarrage automatique suffit pour commencer (décision de Maxime).
- Pas de changement de la complétion (Claude Sonnet 5.5) ni du texte des instructions communes.
- Support-AI n'est ni modifié ni supprimé : il reste sur Gitea comme archive.
**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é.** Aucun code de ce dépôt n'écrit dans une conversation de la production. Seule la préparation de l'instance de test en crée, et Mailpit y piège tout envoi.
- **Ollama joignable depuis Internet.** Ollama n'a aucune authentification. Le serveur a une adresse publique (46.14.212.91, la même que `exchange.sensima.ch`) avec Caddy devant.
- **Casser ce qui tourne déjà sur le serveur** (LibreDesk, et peut-être Gitea derrière le même Caddy) : ne toucher ni à leurs conteneurs, ni à leurs réseaux, ni à leurs volumes, ni à Caddy.
- **Une base de connaissances muette sans qu'on le sache** après le passage : les vecteurs doivent avoir été réellement recalculés avec Ollama, et vérifiés.
- Des connaissances internes (noms de stations ou de clients, commandes d'outils, seuils provisoires) qui entrent dans la base.
## 3. Ce qu'on sait (faits établis)
**La production (2026-11-11)**
- LibreDesk v2.9.0 tourne sur un serveur de l'entreprise. On ne sait pas comment il y a été installé (Docker ou autre) ni par qui. `helpdesk.sensima.ch` répond `Server: libredesk` derrière `Via: 1.1 Caddy`.
- Le serveur est sur le **même réseau interne** que le poste de Maxime : LibreDesk a joint LM Studio à `10.0.2.140:1234` pendant l'essai.
- Maxime aura un **accès SSH direct** au serveur et fera lui-même les gestes. Il ne l'a pas encore.
- Complétion : Claude Sonnet 5.5 (`https://api.anthropic.com/v1`, fournisseur « openai », effort `medium`, `max_tokens` 4096, instructions communes = `instructions.md`). Embeddings : LM Studio comme ci-dessus, clé `lm-studio`, `embedding_max_tokens` 2048. 118 extraits importés. `support_assistant` désactivé ; aucune règle d'automatisation, aucun outil, aucun webhook ; « Learn from resolved conversations » éteint.
- Les étiquettes et le rôle « Agent IA » de l'ancien projet n'ont jamais été créés en production.
- Gitea (`exchange.sensima.ch`, 28.2.0) a les **Packages** activés (registre d'images Docker possible).
**LibreDesk (code v2.9.0 et instance de test)**
- Authentification par clé : `Authorization: token <clé>:<secret>`.
- Extraits de la base : `GET/POST /api/v1/ai/snippets`, `PUT /api/v1/ai/snippets/{id}`, permission `ai:manage` (une clé admin).
- Configuration de l'IA : `PUT /api/v1/ai/config/{completion|embedding}`, et `POST …/test` pour tester sans enregistrer.
- `POST /api/v1/ai/generate-reply` : le brouillon, avec les outils `search_articles` (la base) et l'historique du contact. Il ne voit pas les notes privées. Rien n'est envoyé.
- Les assistants répondent eux-mêmes au client (par mail aussi) : à ne jamais activer.
- LibreDesk appelle `POST <base_url>/embeddings` au format OpenAI ; Ollama expose ce format sous `/v1`.
- **Le recalcul des vecteurs est automatique** (vérifié dans le code v2.9.0, 2026-11-12). Enregistrer une configuration d'embeddings dont l'URL, le modèle ou la dimension change lance un recalcul de toute la base (`internal/ai/ai.go` : journal « embedding provider changed, reindexing knowledge base »). L'empreinte de chaque extrait signe son titre, son texte, l'URL, le modèle et la dimension (`internal/ai/embedsource.go`, `itemFingerprint`) ; un extrait dont l'empreinte ne correspond plus est recalculé, et ceux qui échouent sont retentés chaque minute (`internal/ai/embedding.go`, `reconcileInterval`). Le journal « reconciled embeddings … reindexed N » dit combien ont été recalculés. L'import, lui, ne réécrit qu'un extrait dont le texte a changé : il ne sert pas au recalcul.
## 4. Ce que le dépôt reprend de Support-AI
**Repris** (fichiers copiés, sans l'historique git ; l'historique reste dans Support-AI) :
- `base_connaissances/` : `decoupage.py`, `importer.py`, `instructions.md`, le corpus (`corpus/`, 118 fichiers).
- Les tests de la base : `test_decoupage.py`, `test_corpus.py`, `test_importer.py`, `test_garde_fou_base.py` (le paquet ne parle à LibreDesk que par les routes des extraits), et le faux LibreDesk dont ils ont besoin.
- `instance-de-test/` : `docker-compose.yml`, `preparer_ia.py`, `essayer_brouillons.py`, `mails/`. La préparation de l'instance (`preparer.py`) est **allégée** : elle garde la connexion, la boîte e-mail branchée sur Mailpit et ce dont l'essai a besoin, et perd les étiquettes `tri:*` / `diag:*`, le rôle et l'agent « Agent IA », et la conversation étiquetée.
- La documentation utile, réécrite pour ce dépôt : le document de production (avec ce qui est déjà fait, coché), les constats sur LibreDesk et l'instance de test, les faiblesses connues.
**Pas repris** : `support_diagnostic/`, `agents/`, `.gitea/workflows/`, `cases/`, `instance-de-test/verifier.py` (vérifications de la phase 0, portées sur les notes privées), `mail-exemple.txt`, `base_connaissances/generer.py` (génération ponctuelle déjà faite ; le corpus relu à la main est désormais la source), la spec et les plans de l'ancien projet.
## 5. Les décisions
### Décidées par Maxime
1. Support-LibreDesk remplace complètement Support-AI ; seule l'intégration avec LibreDesk est conservée.
2. Ollama, sur le serveur de LibreDesk.
3. Un conteneur qui contient tout, lancé sur le serveur ; le port ouvert sur le réseau interne, comme LM Studio l'était sur son PC.
4. Tout simuler sur son ordinateur avant de toucher au serveur.
5. Il fait lui-même les gestes sur le serveur, en SSH.
6. Pas d'alerte pour l'instant : le redémarrage automatique suffit.
7. On ne recode pas LibreDesk.
8. Les opérations courantes en tâches VS Code.
### Choix de Claude (à relire)
- **Modèle : bge-m3**, le même qu'avec LM Studio (multilingue : français, allemand, anglais). La version de la bibliothèque Ollama n'a pas la même quantification que celle de LM Studio : les vecteurs diffèrent, il faut **tout recalculer**.
- **Le recalcul des vecteurs** : celui de LibreDesk, déclenché en enregistrant la nouvelle configuration des embeddings (§3). Aucune option d'import, aucune clé admin pour cela. On le prouve par ses journaux (« reconciled embeddings … reindexed 118 ») et, sur l'instance de test seulement, par une lecture des empreintes dans sa base. **Jamais d'écriture SQL** dans une base de LibreDesk. Jamais de suppression d'extrait sans l'accord de Maxime.
- **Le modèle reste chargé en mémoire** pour que le premier brouillon de la journée ne paie pas le chargement. Si la mémoire du serveur manque (environ 1,5 à 2 Go à côté de LibreDesk, Postgres, Redis et peut-être Gitea), on laisse Ollama le décharger après inactivité (son comportement par défaut).
- **Transport de l'image par le registre de Gitea** : construite et poussée depuis le poste de Maxime, récupérée par le serveur. Si le registre refuse une image de cette taille (plus d'un Go), repli : `docker save` puis `docker load` par SSH. Image construite à la main, pas par Gitea Actions.
- **Versions figées** : l'image de base d'Ollama à une version précise, jamais `latest`.
- **Pas de workflow Gitea** dans la première version : les tests se lancent sur le poste (tâche VS Code). Le label du runner de l'entreprise est inconnu et `setup-python` y échoue.
- **Sur le serveur, le port d'Ollama est lié à l'adresse interne du serveur** seulement ; si LibreDesk tourne dans Docker, on peut aussi le joindre par son réseau Docker sans publier de port. Choix fait le jour J, selon ce que Maxime trouve. **Pas de règle de pare-feu ajoutée.** Vérification de l'extérieur du réseau de l'entreprise, par exemple depuis un téléphone en 4G : `http://46.14.212.91:11434` ne doit pas répondre.
- **L'état des lieux du serveur est un point d'arrêt.** S'il manque Docker, si Maxime n'a pas les droits sur Docker, si le serveur n'est pas en x86-64, ou s'il porte lui-même l'adresse publique sur une interface, on s'arrête et Maxime décide (installer Docker, Ollama sans conteneur, autre machine, image multi-architecture). Installer Docker modifie le pare-feu et ajoute un service sur une machine de production. LibreDesk s'installe d'ordinaire avec `docker compose` : c'est le cas attendu.
- **Dans la simulation**, le LibreDesk de test joint Ollama par le réseau Docker de l'instance ; le relais `socat` vers LM Studio n'est plus nécessaire. Seule l'adresse diffère de la production, le protocole est le même.
- **Retour en arrière** : LM Studio reste disponible sur le PC de Maxime jusqu'à ce qu'Ollama soit validé en production ; revenir en arrière = remettre l'ancienne URL et l'ancien modèle, puis recalculer.
- **Les tâches VS Code** (Maxime travaille sous WSL avec VS Code) : au minimum les tests, le démarrage et l'arrêt de l'instance de test, sa préparation, Ollama local, l'essai des brouillons, l'import en simulation, l'import réel. Les tâches qui écrivent dans un LibreDesk le disent dans leur nom et demandent une confirmation ; l'import vise l'instance de test par défaut, la production seulement si l'adresse est donnée explicitement.
- **Les secrets** (clé Anthropic pour l'instance de test, clés admin temporaires) restent dans un `.env` hors de git, comme dans Support-AI.
- **Chaque modification de la production** (serveur ou LibreDesk) est présentée à Maxime et faite seulement avec son accord explicite, un geste à la fois.
- **Documentation et code en français**, comme Support-AI.
## 6. Les étapes
### Étape 1 : le dépôt
Reprendre de Support-AI ce que liste le §4, alléger la préparation de l'instance, faire passer les tests, écrire le `README.md` et les tâches VS Code.
### Étape 2 : la simulation, sur le poste de Maxime
1. Construire l'image (Ollama + bge-m3) ; la lancer ; vérifier qu'elle démarre **sans accès à Internet** et sert bge-m3 (`/v1/models`, puis un appel `/v1/embeddings`). Vérifier le redémarrage automatique.
2. Monter une instance de test neuve, la préparer, brancher ses embeddings d'abord sur LM Studio (l'état de la production), importer la base.
3. Passer les embeddings sur Ollama (test, puis enregistrement) ; LibreDesk **recalcule les 118 vecteurs** (§3). Le prouver : journaux, empreintes toutes changées, la recherche ramène les bons extraits.
4. Relancer l'essai des brouillons (5 mails) : rendus, appuyés sur la base comme avec LM Studio, Mailpit inchangé.
5. Écrire la partie Ollama du document de production à partir de ce qui a marché.
### Étape 3 : la production (Maxime, en SSH)
1. État des lieux, sans rien changer : Docker et les droits de Maxime, architecture, comment tourne LibreDesk (conteneur, réseau), adresse interne, mémoire et disque libres, ports ouverts, ce que relaie Caddy. Point d'arrêt (§5).
2. Récupérer l'image et la lancer (redémarrage automatique, port lié à l'adresse interne ou réseau Docker de LibreDesk).
3. Vérifier qu'Ollama répond et sert bge-m3 depuis la machine (ou le conteneur) de LibreDesk ; vérifier de l'extérieur que le port n'est **pas** joignable.
4. Dans LibreDesk : tester la nouvelle configuration des embeddings, puis l'enregistrer.
5. LibreDesk recalcule les vecteurs des 118 extraits ; le vérifier dans ses journaux.
6. « Generate reply » sur une vraie conversation : le brouillon s'appuie sur la base ; ne rien envoyer.
7. LM Studio n'est plus nécessaire ; le document de production est mis à jour.
Restent ouverts dans le document de production, repris tels quels de Support-AI : la relecture par Maxime des 9 extraits « Savoir métier AIMsight ».
## 7. Ce qui compte pour juger le résultat
- Le dépôt suffit seul : un nouveau venu monte l'instance de test, lance les tests et l'essai des brouillons sans ouvrir Support-AI.
- Ollama tourne sur le serveur, redémarre seul, et n'est joignable que depuis le réseau interne.
- Le test des embeddings de LibreDesk réussit avec Ollama ; les 118 extraits ont des vecteurs calculés par Ollama.
- Les brouillons sont aussi bons qu'avec LM Studio.
- Le PC de Maxime peut être éteint sans effet sur LibreDesk.
- Rien d'autre n'a changé sur le serveur.
## 8. Laissé au constructeur
- L'organisation exacte des dossiers et des fichiers du dépôt.
- La forme de l'image (Dockerfile, façon d'y intégrer le modèle) et de la commande de lancement (`docker compose` ou `docker run`).
- La version exacte d'Ollama et l'étiquette exacte du modèle bge-m3.
- La liste finale des tâches VS Code, dans le cadre du §5.
- Les commandes de vérification et la structure du document de production.
- Le contenu du `README.md`.