diff --git a/README.md b/README.md index e69de29..e50dc3e 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,71 @@ +# Support-LibreDesk : le brouillon de réponse dans LibreDesk + +Les demandes des clients AIMsight arrivent par mail dans LibreDesk (`helpdesk.sensima.ch`). Dans une conversation, le bouton **« Generate reply »** rédige un brouillon dans l'éditeur, appuyé sur une base de connaissances (FAQ, manuel de la station, savoir métier : 118 extraits) et sur les échanges précédents du client. **Rien n'est envoyé : un humain relit et clique lui-même sur « Send ».** + +Ce dépôt porte tout ce qu'il faut pour cela : +- `base_connaissances/` : le corpus relu (un fichier par extrait), les instructions communes (`instructions.md`, à coller dans Admin → IA → Providers → Custom instructions) et l'import vers LibreDesk ; +- `ollama/` : l'image Ollama avec le modèle d'embeddings `bge-m3:567m` embarqué, qui sert la recherche dans la base depuis le serveur de LibreDesk ; +- `instance-de-test/` : un LibreDesk v2.9.0 local avec Mailpit (un piège SMTP : rien ne sort), pour tout essayer avant la production ; +- `.vscode/tasks.json` : les opérations courantes en un clic (Terminal → Run Task). + +Il remplace `Support-AI`, archivé : le diagnostic par des agents qui y était développé est abandonné. + +Design : `docs/superpowers/specs/2026-11-12-support-libredesk-design.md`. Gestes de production : `docs/production.md`. Constats : `docs/verifications.md`. + +## Aucun message ne part au client + +- Aucun code de ce dépôt n'écrit dans une conversation de la production. L'import ne parle à LibreDesk que par les routes des extraits (`tests/test_garde_fou_base.py`). +- Seule l'instance de test crée des conversations, et son SMTP est Mailpit. +- Les assistants IA de LibreDesk (qui répondraient seuls) restent désactivés ; aucune règle d'automatisation. + +## Sur le poste + +Sous WSL (Ubuntu), depuis `~/Support-LibreDesk`. Il faut `python3` (bibliothèque standard seulement, aucun paquet à installer) et Docker. + +```bash +python3 -m unittest discover -s tests -v +``` + +Les secrets restent hors de git : `.env` (la clé Anthropic de l'instance de test, `export ANTHROPIC_API_KEY=…`, et les clés admin temporaires d'un import en production) et `instance-de-test/.env` (écrit par `preparer.py`). + +### L'instance de test + +Tâches « Instance de test : … », ou : + +```bash +bash instance-de-test/demarrer.sh 'TestAdmin-2026!' +``` + +```bash +python3 instance-de-test/preparer.py 'TestAdmin-2026!' +``` + +Puis Ollama sur son réseau (sur ce poste, un Ollama Windows occupe déjà le port 11434 : on publie sur 11435) : + +```bash +docker compose -f ollama/compose.yml build +``` + +```bash +RESEAU_LIBREDESK=ldtest_libredesk OLLAMA_PORT=11435 docker compose -f ollama/compose.yml -f ollama/compose.reseau.yml up -d +``` + +```bash +eval "$(grep '^export ANTHROPIC_API_KEY=' .env)" && python3 instance-de-test/configurer_ia.py 'TestAdmin-2026!' http://ollama:11434/v1 bge-m3:567m +``` + +```bash +set -a && . instance-de-test/.env && set +a && python3 -m base_connaissances.importer --ecrire +``` + +L'essai des brouillons (5 mails, coûte quelques centimes de crédits Anthropic ; rapport dans `cases/`, hors de git) : + +```bash +python3 instance-de-test/essayer_brouillons.py 'TestAdmin-2026!' +``` + +Interface : `http://127.0.0.1:9100` (utilisateur `System`) ; Mailpit : `http://127.0.0.1:9125`. Tout effacer : `docker compose -f instance-de-test/docker-compose.yml -p ldtest down -v`. + +### Retoucher la base de connaissances + +Modifier le fichier dans `base_connaissances/corpus/`, lancer les tests, puis l'import en simulation et en écriture (tâches « Import : … »). L'import apparie par titre, met à jour ce qui a changé et **ne supprime jamais** : un extrait retiré du corpus est seulement signalé. En production, il faut une clé admin temporaire (`docs/production.md`, point 4). diff --git a/docs/production.md b/docs/production.md new file mode 100644 index 0000000..5efa9af --- /dev/null +++ b/docs/production.md @@ -0,0 +1,84 @@ +# Production : le brouillon dans LibreDesk + +LibreDesk en production : `helpdesk.sensima.ch` (v2.9.0). Design : `superpowers/specs/2026-11-12-support-libredesk-design.md`. Constats et simulation : `verifications.md`. + +**Chaque geste est présenté à Maxime et fait seulement avec son accord explicite, un à la fois.** Après chacun, la vérification indiquée. Cocher ici ce qui est fait. + +Rien de ce qui suit n'envoie de message : « Generate reply » pose un brouillon dans l'éditeur, un humain l'envoie. + +## Déjà fait (repris de Support-AI) + +- [ ] **0. Relecture du savoir métier par Maxime.** Les 9 extraits de `base_connaissances/corpus/` dont la source est « Savoir métier AIMsight » ont été réécrits à la main à partir des notes d'analyse : vérifier qu'ils sont justes et bons à dire à un client. +- [x] **0 bis. Assistant** (2026-11-11). Admin → IA → Assistants : `support_assistant` désactivé (il répondrait seul aux clients si une règle lui confiait une conversation). Vérification : statut « Disabled ». +- [x] **0 ter. Rien d'automatique** (vérifié le 2026-11-11). Admin → Automations : aucune règle ; Admin → IA → Tools : aucun outil ; aucun webhook ; Admin → IA → Suggestions : « Learn from resolved conversations » désactivé. +- [x] **1 provisoire. LM Studio sur le PC de Maxime** (2026-11-11). `text-embedding-bge-m3` (bge-m3 Q8_0) sur `http://10.0.2.140:1234/v1` (adresse Wi-Fi attribuée par DHCP). Le PC doit rester allumé, LM Studio lancé avec son serveur actif. **Remplacé par Ollama ci-dessous.** +- [x] **2. Embeddings** (2026-11-11). Fournisseur OpenAI, URL `http://10.0.2.140:1234/v1`, modèle `text-embedding-bge-m3`, clé `lm-studio`, *embedding max tokens* 2048. +- [x] **3. Complétion** (2026-11-11). *Max tokens* 4096 ; *Custom instructions* = `base_connaissances/instructions.md` ; Claude Sonnet 5.5, `https://api.anthropic.com/v1`, effort `medium`. +- [x] **4. Import de la base** (2026-11-11). 118 extraits actifs. Agent « Import base » (id 127) : clé révoquée, agent désactivé. Pour un réimport : regénérer une clé, réactiver l'agent, mettre la clé dans `.env` (`export LIBREDESK_ADMIN_KEY=…`, `export LIBREDESK_ADMIN_SECRET=…`), tâche « Import : simulation (PRODUCTION) » puis « Import : ÉCRIRE (PRODUCTION) », puis tout révoquer. +- [x] **5. Premiers brouillons** (2026-11-11, Maxime) : deux brouillons sur de vraies conversations, rien envoyé par l'IA. + +## Ollama sur le serveur + +But : remplacer LM Studio par Ollama (`bge-m3:567m`) sur le serveur de LibreDesk. LibreDesk recalcule seul les vecteurs des 118 extraits quand on enregistre la nouvelle adresse (vérifié sur l'instance de test, `verifications.md`). + +- [ ] **6. L'image.** Sur le poste, tâche « Ollama : construire » (ou `docker compose -f ollama/compose.yml build`), puis vérification hors ligne (`verifications.md`). Puis, avec l'accord de Maxime, la pousser au registre Gitea : jeton Gitea à portée `write:package`, `docker login exchange.sensima.ch`, `docker push exchange.sensima.ch/maxime.pasquier/ollama-bge-m3:0.40.16-567m`. + Vérification : l'image apparaît dans Packages du compte. Si le registre la refuse (taille), on la transportera par SSH au point 8. + +- [ ] **7. État des lieux du serveur, sans rien changer** (Maxime, en SSH). + ```bash + docker version && id && uname -m + docker ps --format '{{.Names}} {{.Image}} {{.Networks}} {{.Ports}}' + ip -brief addr + free -h && df -h /var/lib/docker + sudo ss -ltnp + systemctl is-enabled docker + ``` + Et la configuration de Caddy, en lecture (`docker exec cat /etc/caddy/Caddyfile`, ou `/etc/caddy/Caddyfile`). + **Point d'arrêt** : on s'arrête et Maxime décide si Docker manque, si Maxime n'est pas dans le groupe `docker` (ou sans `sudo`), si `uname -m` n'est pas `x86_64`, si `ip -brief addr` montre l'adresse publique 46.14.212.91 sur une interface du serveur, si la mémoire libre est sous 2 Go, ou si le disque a moins de 5 Go libres. Noter : le nom du conteneur et du réseau de LibreDesk (s'il est dans Docker), l'adresse interne du serveur (`10.…`), et que le port 11434 est libre. + +- [ ] **8. Installer Ollama.** Copier le dossier `ollama/` du dépôt sur le serveur (`scp -r ollama :~/`). Récupérer l'image : `docker login exchange.sensima.ch && docker pull exchange.sensima.ch/maxime.pasquier/ollama-bge-m3:0.40.16-567m` ; ou, si le registre l'a refusée, depuis le poste : `docker save exchange.sensima.ch/maxime.pasquier/ollama-bge-m3:0.40.16-567m | gzip | ssh 'gunzip | docker load'`. + Puis écrire `~/ollama/.env` sur le serveur (Docker Compose le lit à chaque lancement, le réglage survit aux redémarrages), selon l'état des lieux : + - **LibreDesk dans Docker** (cas attendu) : `RESEAU_LIBREDESK=`. Lancer : `cd ~/ollama && docker compose -f compose.yml -f compose.reseau.yml up -d`. Adresse pour LibreDesk : `http://ollama:11434/v1`. Le port n'est publié que sur `127.0.0.1` du serveur. + - **LibreDesk hors de Docker** : `OLLAMA_BIND=`. Lancer : `cd ~/ollama && docker compose -f compose.yml up -d`. Adresse pour LibreDesk : `http://:11434/v1`. + Vérification : `docker ps --filter name=ollama-bge-m3` montre `Up … (healthy)` ; `docker inspect ollama-bge-m3 --format '{{.HostConfig.RestartPolicy.Name}}'` rend `unless-stopped`. + +- [ ] **9. Vérifier Ollama.** + - Depuis le serveur : `python3 ~/ollama/verifier.py http://127.0.0.1:11434/v1` (ou l'adresse interne) → `OK bge-m3:567m, 1024 dimensions`. + - Depuis le réseau de LibreDesk (cas Docker) : `docker run --rm --network -v ~/ollama:/o:ro python:3.12-alpine python /o/verifier.py http://ollama:11434/v1` → même résultat. + - **De l'extérieur** : depuis un téléphone en 4G (Wi-Fi coupé), ouvrir `http://46.14.212.91:11434` : la page **ne doit pas répondre**. Si elle répond (« Ollama is running »), arrêter Ollama (`docker compose down`) et revoir le point 7 avec la personne qui gère le serveur. + - **Ne pas redémarrer le service Docker pour essayer** : cela redémarrerait aussi LibreDesk. `systemctl is-enabled docker` (point 7) et la politique `unless-stopped` suffisent ; le prochain redémarrage planifié du serveur le confirmera (vérifier alors `docker ps`). + +- [ ] **10. Brancher LibreDesk sur Ollama.** Admin → IA → Providers, Embeddings : fournisseur OpenAI, URL de l'étape 8, modèle `bge-m3:567m`, clé `ollama`, *dimensions* 0, *embedding max tokens* 2048. Bouton de test, puis enregistrer seulement s'il réussit. + Vérification : le test réussit ; la complétion n'a pas changé. + +- [ ] **11. Le recalcul.** LibreDesk recalcule seul les 118 extraits (environ une minute). Dans ses journaux (`docker logs --since 10m 2>&1 | grep -E "embedding provider changed|reconciled embeddings|error generating embeddings"`) : + - « embedding provider changed, reindexing knowledge base » avec `new_base_url` = l'adresse d'Ollama ; + - puis « reconciled embeddings … reindexed=118 » ; + - et **aucune** « error generating embeddings » après. Attention : « reindexed=118 » compte les extraits *tentés* ; s'il y a des erreurs, LibreDesk retente chaque minute (Ollama joignable ?), attendre qu'elles cessent. + +- [ ] **12. Premier brouillon avec Ollama.** Sur une vraie conversation dont la question est dans la base, « Generate reply » : le brouillon arrive et s'appuie sur la base (`docker logs … | grep search_articles` montre des scores autour de 0,5). **Ne rien envoyer** ; effacer le brouillon ou le laisser à l'agent qui suit la conversation. + +- [ ] **13. LM Studio n'est plus nécessaire.** Le PC de Maxime peut être éteint ; garder LM Studio installé quelques jours pour le retour en arrière. + +### Retour en arrière +Admin → IA → Providers, Embeddings : remettre `http://10.0.2.140:1234/v1`, `text-embedding-bge-m3`, clé `lm-studio` (LM Studio lancé sur le PC de Maxime), tester, enregistrer : LibreDesk recalcule de nouveau. Puis `cd ~/ollama && docker compose down` sur le serveur si besoin. + +## Au quotidien + +- **Si Ollama est arrêté**, « Generate reply » rend quand même un brouillon, mais **sans la base de connaissances**, et rien ne le signale à l'agent (journaux de LibreDesk : `AI provider unavailable`, `search_articles` en erreur). Si les brouillons deviennent vagues : `docker ps --filter name=ollama-bge-m3` et `python3 ~/ollama/verifier.py …` sur le serveur ; `docker start ollama-bge-m3` s'il a été arrêté à la main (un arrêt manuel n'est pas relancé seul). +- **Retoucher la base** : modifier le fichier dans `base_connaissances/corpus/`, puis réimporter (point 4). Un extrait renommé ou retiré du corpus est signalé (« dans LibreDesk mais pas dans le corpus ») et **n'est pas supprimé** : le désactiver ou le supprimer à la main dans Admin → IA → Snippets. +- **Changer de version d'Ollama** : modifier `ollama/Dockerfile`, reconstruire, revérifier hors ligne et sur l'instance de test, puis refaire les points 6, 8 et 9. Même modèle, même adresse : pas de recalcul. + +## Plus tard + +- Les guides de lecture et les fiches d'incident, une fois réécrits (décision de Maxime : hors de la première version). +- Les règles d'automatisation simples (étiquettes, attribution) : à décider. +- Une alerte si Ollama ne répond plus (décision de Maxime : le redémarrage automatique suffit pour commencer). + +## Petites faiblesses connues + +- Les puces « • » des PDF ne sont pas converties en listes dans quelques extraits (cosmétique). +- L'import réactive un extrait désactivé à la main quand son contenu change, écrase un extrait appris de même titre, et n'affiche que des comptes en écriture. La liste des extraits n'est pas paginée. +- Lancer l'import depuis un Python Windows pourrait mal lire les accents : toujours passer par WSL. +- `essayer_brouillons.py` est fragile si la réponse est vide ou tardive. +- La clé d'import a le rôle Admin ; un rôle limité à `ai:manage` suffirait. diff --git a/docs/verifications.md b/docs/verifications.md index 0e5e90e..daad4ac 100644 --- a/docs/verifications.md +++ b/docs/verifications.md @@ -2,6 +2,28 @@ Les constats sur lesquels repose ce dépôt, datés, avec leur source : **[code]** le code de LibreDesk v2.9.0 ; **[test]** l'instance de test (`instance-de-test/`) ; **[prod]** la production. +## LibreDesk v2.9.0 + +Repris de Support-AI (vérifications des 2026-11-09 et 2026-11-11), limité à ce qui sert ici. + +| Point | Constat | Source | +|---|---|---| +| Version en production | v2.9.0 (`GET /api/v1/settings/general`) ; derrière Caddy (`Via: 1.1 Caddy`), même adresse publique que `exchange.sensima.ch` | [prod] | +| Authentification par clé | `Authorization: token :`, une clé par agent (Admin → Teammates → Agents) | [code, test] | +| Extraits de la base | `GET/POST /api/v1/ai/snippets`, `PUT /api/v1/ai/snippets/{id}` ; permission `ai:manage` (clé admin) ; extraits privés, lus par l'IA seulement | [code, test] | +| Configuration de l'IA | `PUT /api/v1/ai/config/{completion,embedding}` ; `POST …/test` fait une vraie requête sans enregistrer | [code, test] | +| Embeddings | format OpenAI, `POST /embeddings` ; vecteurs de toute dimension (bge-m3 : 1024) ; garde SSRF désactivée par défaut (`[ssrf] enabled = false`) | [code] | +| Recalcul des vecteurs | automatique quand l'URL, le modèle ou la dimension change (`internal/ai/ai.go`) ; empreinte = titre, texte, URL, modèle, dimension (`internal/ai/embedsource.go`, `itemFingerprint`) ; échecs retentés chaque minute (`internal/ai/embedding.go`, `reconcileInterval`) | [code, test] | +| « Generate reply » | `POST /api/v1/ai/generate-reply` ; outils `search_articles`, `list_contact_conversations`, `fetch_conversation` ; **ne voit pas les notes privées** ; rien n'est envoyé, le texte revient à l'éditeur | [code, test] | +| Sans embeddings | le brouillon est rendu quand même, sans la base (« AI provider unavailable », `search_articles` en erreur), rien ne le signale | [test] | +| Assistants | répondent eux-mêmes au client, par mail aussi (`internal/aiagent/worker.go`) : **à ne jamais activer** | [code] | +| Envoi d'un message | même route pour une note privée et une réponse ; sans `private: true`, le mail part (vérifié avec Mailpit) : aucun code de ce dépôt n'appelle cette route en production | [test] | +| Complétion par Claude | fournisseur `openai`, `https://api.anthropic.com/v1`, `claude-sonnet-5-5`, `reasoning_effort` `medium` : les tests de configuration et les appels d'outils fonctionnent | [test, prod] | + +**L'essai avec LM Studio (2026-11-11)** : 118 extraits importés et indexés ; 5 brouillons sur 5 en 4 à 11 s, appuyés sur la FAQ et le manuel, dans la langue du client (allemand compris), sans rien inventer hors base ; Mailpit inchangé. Une seule réserve : un brouillon mélangeait « tu » et « vous » (instructions corrigées depuis). + +**Le réseau du poste** : WSL est en mode `networkingMode=mirrored` ; WSL et Docker ne joignent Windows que par `127.0.0.1`. Pour qu'un conteneur joigne LM Studio sur Windows, il fallait un relais `socat` (voir l'historique de Support-AI) ; avec Ollama dans Docker, le réseau Docker de l'instance suffit. + ## La simulation du passage à Ollama (2026-11-12) [test] Instance de test neuve (LibreDesk v2.9.0, Mailpit), base importée (118 extraits), image `exchange.sensima.ch/maxime.pasquier/ollama-bge-m3:0.40.16-567m` (Ollama 0.40.16, `bge-m3:567m`, **2,43 Go**) sur le réseau Docker de l'instance (`ollama/compose.reseau.yml`).