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,231 @@
# Support-LibreDesk : plan de réalisation
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal :** un dépôt autonome qui porte le brouillon de réponse de LibreDesk (base de connaissances, import, instructions communes, instance de test, tâches VS Code) et l'image Ollama + bge-m3 qui remplace LM Studio en production, éprouvée sur le poste de Maxime.
**Architecture :** on reprend de `~/Support-AI` le paquet `base_connaissances/` et ses tests (Python, bibliothèque standard seulement), on reconstruit une instance de test allégée (LibreDesk v2.9.0 + Mailpit, scripts de préparation partageant une session commune), on ajoute un dossier `ollama/` (Dockerfile qui embarque le modèle, compose, script de vérification) et des tâches VS Code. LibreDesk recalcule lui-même les vecteurs quand la configuration des embeddings change : aucun code de recalcul.
**Tech Stack :** Python 3.12 (stdlib, `unittest`), Docker / Docker Compose, Ollama, LibreDesk v2.9.0, VS Code (tâches, sous WSL).
**Spec :** `docs/superpowers/specs/2026-11-12-support-libredesk-design.md`
## Global Constraints
- **Rien ne part chez un client.** Aucun code n'écrit dans une conversation de la production. Seule la préparation de l'instance de test crée des conversations ; son SMTP est Mailpit.
- **On ne recode pas LibreDesk** : ni son code, ni son conteneur, ni son reverse proxy. Configuration et API seulement. **Jamais d'écriture SQL** dans une base de LibreDesk (lecture SQL autorisée sur l'instance de test seulement).
- `base_connaissances/` ne parle à LibreDesk que par `/api/v1/ai/snippets` et `/api/v1/ai/snippets/{id}` ; jamais `/messages`, `/conversations`, `DELETE`, `automations`, `assistants` (test `test_garde_fou_base`).
- L'import simule par défaut ; il n'écrit qu'avec `--ecrire`. Il ne supprime jamais un extrait.
- Le corpus ne contient ni noms de stations (`BREITHORN, CLARIDEN, FLORIDA, JUNGFRAU, LENZSPITZE, MICHIGAN, NADELHORN, NEBRASKA, NIEDERHORN, NORDEND, SNCF01, SUSTENHORN, WILDSTRUBEL, VERMONT, WEISSHORN, MISSISSIPPI`), ni commandes d'outils, ni seuils provisoires, ni prénom interne (`Marc`).
- Modèle d'embeddings : `bge-m3` de la bibliothèque Ollama, étiquette figée **`bge-m3:567m`** (dimension 1024). Configuration LibreDesk : fournisseur `openai`, `base_url` `http://<hôte>:11434/v1`, modèle `bge-m3:567m`, clé `ollama`, `dimensions` 0, `embedding_max_tokens` 2048.
- Image de base Ollama à une **version figée** (`ollama/ollama:<x.y.z>`, la dernière stable au moment de la construction, notée dans le Dockerfile), jamais `latest`. Modèle gardé chargé : `OLLAMA_KEEP_ALIVE=-1`.
- Port d'Ollama publié sur `127.0.0.1` par défaut ; une autre adresse seulement par la variable `OLLAMA_BIND`. Jamais `0.0.0.0` par défaut.
- Complétion de l'instance de test (comme la production) : fournisseur `openai`, `base_url` `https://api.anthropic.com/v1`, modèle `claude-sonnet-5-5`, `max_tokens` 4096, `reasoning_effort` `medium`, instructions = `base_connaissances/instructions.md`.
- Secrets dans `.env` (racine) et `instance-de-test/.env`, hors de git. Ne jamais afficher une clé.
- Commandes `python3`, `git`, `docker` lancées sous WSL (Ubuntu), depuis `~/Support-LibreDesk`. Tests : `python3 -m unittest discover -s tests -v`.
- Code, documents et messages de commit en français. Commits terminés par `Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>`.
- Support-AI n'est ni modifié ni supprimé : on y lit seulement.
- Toute modification de la production (serveur, LibreDesk) : présentée à Maxime, faite par lui ou avec son accord explicite, un geste à la fois. Aucune tâche de ce plan ne touche la production ; le registre Gitea n'est poussé qu'avec l'accord de Maxime (Task 3, dernière étape).
## Review Focus
1. **Ollama arrêté pendant le recalcul** (conteneur tombé juste après le changement de configuration) : LibreDesk doit retenter chaque minute et finir par recalculer les 118 extraits une fois Ollama revenu. → Task 4, étape « panne pendant le recalcul ».
2. **Serveur sans accès à Internet** : l'image doit servir bge-m3 sans rien télécharger. → Task 3, `verifier.py` sur un réseau Docker `--internal`.
3. **Une tâche VS Code d'import lancée contre la production par erreur** : aucune tâche n'écrit en production sans adresse tapée et confirmation. → Task 5, `test_ecriture_production_demande_confirmation`.
4. **Le port d'Ollama ouvert sur toutes les interfaces** par un oubli de variable : le compose publie sur `127.0.0.1` par défaut. → Task 3, `test_port_lie_a_localhost_par_defaut`.
5. **`preparer.py` relancé sur une instance déjà préparée** : il doit s'arrêter avec un message clair, sans créer de doublon (boîte, agent). → Task 2, étape de vérification « deuxième passage ».
---
## Structure
| Fichier | Rôle |
|---|---|
| `.gitignore` | `.env`, `instance-de-test/.env`, `instance-de-test/config.toml`, `instance-de-test/uploads/`, `__pycache__/`, `cases/` |
| `base_connaissances/__init__.py`, `decoupage.py`, `importer.py`, `instructions.md`, `corpus/*.md` | repris tels quels de Support-AI (sauf docstrings qui citent Support-AI) |
| `tests/faux_libredesk.py`, `test_decoupage.py`, `test_corpus.py`, `test_importer.py`, `test_garde_fou_base.py` | repris ; `test_corpus.py` complété (2 stations) |
| `instance-de-test/docker-compose.yml`, `mails/` | repris |
| `instance-de-test/session.py` | connexion admin (cookie + CSRF) et `req()`, partagés par les scripts |
| `instance-de-test/demarrer.sh` | crée `config.toml` si absent, lance l'instance |
| `instance-de-test/preparer.py` | boîte Mailpit + agent « Import base » et sa clé → `instance-de-test/.env` |
| `instance-de-test/configurer_ia.py` | complétion + embeddings (test puis enregistrement), rejouable |
| `instance-de-test/essayer_brouillons.py` | repris, branché sur `session.py` |
| `instance-de-test/empreintes.sh` | lecture SQL des empreintes des extraits (instance de test seulement) |
| `ollama/Dockerfile`, `ollama/compose.yml`, `ollama/compose.reseau.yml` | l'image et son lancement |
| `ollama/verifier.py` | vérifie qu'une URL sert `bge-m3:567m` en dimension 1024 |
| `tests/test_ollama.py` | `verifier.py` contre un faux serveur ; contrôles du compose |
| `.vscode/tasks.json`, `tests/test_taches.py` | les tâches et leurs garde-fous |
| `README.md`, `docs/production.md`, `docs/verifications.md` | mode d'emploi, gestes de production, constats |
---
### Task 1 : la base de connaissances reprise
**Files:**
- Create: `.gitignore`, `base_connaissances/{__init__.py,decoupage.py,importer.py,instructions.md}`, `base_connaissances/corpus/` (118 fichiers), `tests/{faux_libredesk.py,test_decoupage.py,test_corpus.py,test_importer.py,test_garde_fou_base.py}`
- Source : `~/Support-AI/` mêmes chemins. **Ne pas** copier `base_connaissances/generer.py`.
**Interfaces:**
- Produces: `python3 -m base_connaissances.importer [--ecrire]` (lit `LIBREDESK_URL`, `LIBREDESK_ADMIN_KEY`, `LIBREDESK_ADMIN_SECRET`) ; `base_connaissances.decoupage.lire_corpus(dossier: Path) -> list[Extrait]`.
- [ ] **Step 1 : Copier les fichiers** listés ci-dessus et écrire `.gitignore` (contenu de la Structure).
- [ ] **Step 2 : Ajouter `"WEISSHORN", "MISSISSIPPI"` à `STATIONS` dans `tests/test_corpus.py`.**
- [ ] **Step 3 : Retirer des docstrings et commentaires toute mention de `support_diagnostic`, de « spec §… » de Support-AI ou de `generer.py`** (`grep -rn "support_diagnostic\|generer\|spec §" base_connaissances tests` ne rend rien ; remplacer « spec §x » par une référence au design de ce dépôt ou la supprimer).
- [ ] **Step 4 : Lancer les tests.** Run : `python3 -m unittest discover -s tests -v`. Expected : tous OK (les 4 fichiers), 118 extraits lus par `test_corpus_present`.
- [ ] **Step 5 : Simulation d'import à vide.** Run : `LIBREDESK_URL=http://127.0.0.1:1 LIBREDESK_ADMIN_KEY=x LIBREDESK_ADMIN_SECRET=x python3 -m base_connaissances.importer`. Expected : échec réseau clair (aucune instance), pas d'écriture.
- [ ] **Step 6 : Commit** — `git add .gitignore base_connaissances tests docs/superpowers && git commit -m "Base de connaissances reprise de Support-AI : corpus, import, instructions, tests"` (le design et ce plan entrent dans ce premier commit).
---
### Task 2 : l'instance de test allégée
**Files:**
- Create: `instance-de-test/docker-compose.yml` (repris tel quel), `instance-de-test/mails/` (repris), `instance-de-test/session.py`, `instance-de-test/demarrer.sh`, `instance-de-test/preparer.py`, `instance-de-test/configurer_ia.py`, `instance-de-test/essayer_brouillons.py`, `instance-de-test/empreintes.sh`
**Interfaces:**
- Consumes: Task 1 (`base_connaissances/instructions.md`, l'importeur).
- Produces:
- `session.py` : `B = "http://127.0.0.1:9100"` ; `connexion(mot_de_passe: str) -> None` ; `req(methode: str, chemin: str, corps: dict | None = None, timeout: int = 60) -> object` (rend `data`, `sys.exit` avec code et 300 premiers caractères en cas d'erreur HTTP, **n'affiche jamais le corps envoyé**). Reprend la connexion de `~/Support-AI/instance-de-test/preparer_ia.py` (cookie `Secure` désactivé, `csrf_token` fixé à `t0k3n`, en-tête `X-CSRFTOKEN`).
- `demarrer.sh <mot de passe System>` : si `config.toml` manque, le télécharge depuis `https://raw.githubusercontent.com/abhinavxd/libredesk/v2.9.0/config.sample.toml` et y met une `encryption_key` aléatoire (commande de `~/Support-AI/docs/verifications.md`, « L'instance de test ») ; puis `LIBREDESK_SYSTEM_USER_PASSWORD=… docker compose -p ldtest up -d` ; attend que `GET /api/v1/settings/general` réponde (60 s max).
- `preparer.py <mot de passe System>` : crée la boîte e-mail « Test » (SMTP = Mailpit, configuration de `~/Support-AI/instance-de-test/preparer.py`), l'agent « Import base » (rôle `Admin`, e-mail `import@example.com`) et sa clé ; **écrase** `instance-de-test/.env` avec `LIBREDESK_URL=http://127.0.0.1:9100`, `LIBREDESK_ADMIN_KEY=…`, `LIBREDESK_ADMIN_SECRET=…`. Si une boîte « Test » existe déjà : `sys.exit("instance déjà préparée : docker compose -p ldtest down -v, puis demarrer.sh")` avant toute écriture. Ne crée ni étiquette, ni rôle « Agent IA », ni conversation.
- `configurer_ia.py <mot de passe System> <url des embeddings> <modèle> [clé]` (clé par défaut `ollama`) : `ANTHROPIC_API_KEY` lu dans l'environnement ; pour `completion` puis `embedding`, `POST /api/v1/ai/config/{type}/test` puis `PUT /api/v1/ai/config/{type}` (valeurs des Global Constraints) ; affiche `"{type} : test réussi, configuration enregistrée"`. Rejouable : c'est lui qui fait passer l'instance de LM Studio à Ollama.
- `essayer_brouillons.py [mot de passe System]` : repris de Support-AI, connexion par `session.py`, rapport dans `cases/essai-brouillons-<date>.md`.
- `empreintes.sh` : `docker exec ldtest_db psql -U libredesk -d libredesk -At -c "SELECT id, embedded_fingerprint FROM ai_knowledge_base WHERE enabled ORDER BY id"` — lecture seule.
- [ ] **Step 1 : Écrire `session.py`, `demarrer.sh`, `preparer.py`, `configurer_ia.py`, `empreintes.sh` ; adapter `essayer_brouillons.py`** aux interfaces ci-dessus.
- [ ] **Step 2 : Monter une instance neuve.** Run : `docker compose -p ldtest down -v; bash instance-de-test/demarrer.sh 'TestAdmin-2026!'`. Expected : l'interface répond sur `http://127.0.0.1:9100`.
- [ ] **Step 3 : Préparer.** Run : `python3 -I instance-de-test/preparer.py 'TestAdmin-2026!'`. Expected : `instance-de-test/.env` contient les trois variables.
- [ ] **Step 4 : Deuxième passage (Review Focus 5).** Run : la même commande. Expected : sortie « instance déjà préparée … », code ≠ 0, toujours une seule boîte « Test » (`GET /api/v1/inboxes`).
- [ ] **Step 5 : Configurer l'IA sur LM Studio, l'état de la production** (relais `socat` de `~/Support-AI/docs/verifications.md`, LM Studio lancé par Maxime). Run : `eval "$(grep '^export ANTHROPIC_API_KEY=' .env)" && python3 -I instance-de-test/configurer_ia.py 'TestAdmin-2026!' http://$GW:11234/v1 text-embedding-bge-m3 lm-studio`. Expected : deux « test réussi ». Si LM Studio n'est pas disponible : sauter cette étape et le noter ; la Task 4 passe alors d'une première URL d'Ollama à une seconde (l'alias réseau), ce qui prouve le même déclenchement.
- [ ] **Step 6 : Importer.** Run : `set -a && . instance-de-test/.env && set +a && python3 -m base_connaissances.importer --ecrire`. Expected : `créés 118`. Rejoué : `inchangés 118`.
- [ ] **Step 7 : Commit** — `git add instance-de-test && git commit -m "Instance de test allégée : démarrage, préparation, configuration de l'IA, essai des brouillons"`.
---
### Task 3 : l'image Ollama
**Files:**
- Create: `ollama/Dockerfile`, `ollama/compose.yml`, `ollama/compose.reseau.yml`, `ollama/verifier.py`, `tests/test_ollama.py`
**Interfaces:**
- Produces:
- Image `exchange.sensima.ch/maxime.pasquier/ollama-bge-m3:<version d'Ollama>-567m`, construite par `docker compose -f ollama/compose.yml build`. Le Dockerfile télécharge `bge-m3:567m` pendant la construction (serveur lancé en arrière-plan le temps d'un `ollama pull`) ; `ENV OLLAMA_HOST=0.0.0.0:11434 OLLAMA_KEEP_ALIVE=-1` ; `HEALTHCHECK` par `ollama list`.
- `compose.yml` : service `ollama`, `container_name: ollama-bge-m3`, `restart: unless-stopped`, port `"${OLLAMA_BIND:-127.0.0.1}:11434:11434"`.
- `compose.reseau.yml` (surcharge) : rattache le service au réseau externe `${RESEAU_LIBREDESK}` avec l'alias `ollama`. Localement `RESEAU_LIBREDESK=ldtest_libredesk` ; sur le serveur, le réseau de LibreDesk s'il est dans Docker.
- `ollama/verifier.py <base_url>` (stdlib) : `GET <base_url>/models` doit lister `bge-m3:567m` ; `POST <base_url>/embeddings {"model":"bge-m3:567m","input":"Quelle est l'autonomie de la batterie ?"}` doit rendre un vecteur de 1024 nombres. Affiche `OK bge-m3:567m, 1024 dimensions` et sort en 0 ; sinon un message qui dit ce qui manque, sort en 1. Fonction testable : `verifier(base_url: str) -> str` (lève `RuntimeError` avec le message).
- [ ] **Step 1 : Écrire les tests** dans `tests/test_ollama.py` (faux serveur `http.server` local, comme `faux_libredesk.py`) :
```python
def test_modele_et_dimension_ok(self): # /models liste bge-m3:567m, /embeddings rend 1024 floats
self.assertIn("1024", verifier(self.url))
def test_modele_absent(self): # /models sans bge-m3:567m
with self.assertRaisesRegex(RuntimeError, "bge-m3:567m"): verifier(self.url)
def test_mauvaise_dimension(self): # vecteur de 768
with self.assertRaisesRegex(RuntimeError, "768"): verifier(self.url)
def test_port_lie_a_localhost_par_defaut(self): # Review Focus 4
self.assertIn('"${OLLAMA_BIND:-127.0.0.1}:11434:11434"', COMPOSE.read_text())
def test_version_figee(self): # FROM ollama/ollama:<x.y.z>, jamais latest
self.assertRegex(DOCKERFILE.read_text(), r"FROM ollama/ollama:\d+\.\d+\.\d+")
self.assertIn("bge-m3:567m", DOCKERFILE.read_text())
```
- [ ] **Step 2 : Lancer, vérifier l'échec.** Run : `python3 -m unittest tests.test_ollama -v`. Expected : FAIL (module ou fichiers absents).
- [ ] **Step 3 : Écrire `verifier.py`, le Dockerfile et les deux compose.**
- [ ] **Step 4 : Tests verts.** Run : `python3 -m unittest tests.test_ollama -v`. Expected : PASS.
- [ ] **Step 5 : Construire.** Run : `docker compose -f ollama/compose.yml build`. Expected : image construite ; noter sa taille.
- [ ] **Step 6 : Sans Internet (Review Focus 2).** Run : `docker network create --internal ollama-hors-ligne && docker run -d --name ollama-test --network ollama-hors-ligne <image> && sleep 10 && docker run --rm --network ollama-hors-ligne -v "$PWD/ollama:/o:ro" python:3.12-alpine python /o/verifier.py http://ollama-test:11434/v1; docker rm -f ollama-test; docker network rm ollama-hors-ligne`. Expected : `OK bge-m3:567m, 1024 dimensions`.
- [ ] **Step 7 : Lancement et redémarrage.** Run : `docker compose -f ollama/compose.yml up -d && sleep 10 && python3 ollama/verifier.py http://127.0.0.1:11434/v1`, puis `docker kill ollama-bge-m3 && sleep 15 && docker ps --filter name=ollama-bge-m3`. Expected : `OK …`, puis le conteneur est de nouveau `Up` (après un `docker kill`, `unless-stopped` relance). Puis `sudo service docker restart` (ou redémarrage de Docker Desktop) : conteneur relancé.
- [ ] **Step 8 : Commit** — `git add ollama tests/test_ollama.py && git commit -m "Ollama : image avec bge-m3 embarqué, lancement, vérification"`.
- [ ] **Step 9 (avec l'accord explicite de Maxime seulement) : pousser l'image au registre Gitea.** Maxime crée un jeton Gitea (portée `write:package`) et fait `docker login exchange.sensima.ch`. Run : `docker push exchange.sensima.ch/maxime.pasquier/ollama-bge-m3:<tag>`. Expected : l'image apparaît dans Packages du compte. En cas de refus (taille, `413`) : noter l'erreur dans `docs/verifications.md` ; le repli `docker save | ssh … docker load` sera décrit dans `docs/production.md` (Task 6).
---
### Task 4 : la simulation du passage à Ollama
**Files:**
- Modify: `docs/verifications.md` (créé ici : constats datés)
**Interfaces:**
- Consumes: Task 2 (instance préparée, importée, embeddings sur LM Studio), Task 3 (image, `compose.reseau.yml`, `verifier.py`).
- [ ] **Step 1 : Relever les empreintes « avant ».** Run : `bash instance-de-test/empreintes.sh > /tmp/avant.txt && wc -l /tmp/avant.txt`. Expected : 118 lignes, aucune empreinte vide.
- [ ] **Step 2 : Lancer Ollama sur le réseau de l'instance.** Run : `RESEAU_LIBREDESK=ldtest_libredesk docker compose -f ollama/compose.yml -f ollama/compose.reseau.yml up -d && docker run --rm --network ldtest_libredesk -v "$PWD/ollama:/o:ro" python:3.12-alpine python /o/verifier.py http://ollama:11434/v1`. Expected : `OK bge-m3:567m, 1024 dimensions`.
- [ ] **Step 3 : Basculer l'instance sur Ollama.** Run : `python3 -I instance-de-test/configurer_ia.py 'TestAdmin-2026!' http://ollama:11434/v1 bge-m3:567m`. Expected : deux « test réussi ».
- [ ] **Step 4 : Le recalcul.** Run : `docker logs ldtest_app 2>&1 | grep -E "embedding provider changed|reconciled embeddings"` puis `bash instance-de-test/empreintes.sh > /tmp/apres.txt`. Expected : « embedding provider changed, reindexing knowledge base » puis « reconciled embeddings … reindexed 118 » ; 118 lignes dans `apres.txt`, aucune empreinte vide, **aucune identique** à `avant.txt` (`comm -12 <(sort /tmp/avant.txt) <(sort /tmp/apres.txt)` vide).
- [ ] **Step 5 : Panne pendant le recalcul (Review Focus 1).** Repasser sur LM Studio (ou sur une URL d'Ollama différente, p. ex. `http://ollama-bge-m3:11434/v1`), puis : `docker stop ollama-bge-m3`, rebasculer sur `http://ollama:11434/v1` **sans** test (enregistrement direct : `configurer_ia.py` échouerait au test ; faire l'enregistrement par l'interface Admin → IA → Providers), attendre 2 min, `docker start ollama-bge-m3`, attendre 2 min. Expected : erreurs d'embedding dans les journaux pendant la panne, puis « reconciled embeddings … reindexed 118 » après le redémarrage ; empreintes toutes non vides.
- [ ] **Step 6 : L'essai des brouillons.** Run : `python3 -I instance-de-test/essayer_brouillons.py`. Expected : 5 brouillons `completed`, « Mailpit inchangé pendant la génération ». Comparer au rapport LM Studio (`~/Support-AI/cases/essai-brouillons-2026-11-11.md`) : appuyés sur la base de la même façon ; le faire juger par Maxime.
- [ ] **Step 7 : Consigner** dans `docs/verifications.md` : date, version d'Ollama, taille de l'image, extraits des journaux, résultat des empreintes, de la panne et de l'essai.
- [ ] **Step 8 : Commit** — `git add docs/verifications.md && git commit -m "Simulation : passage de LM Studio à Ollama, recalcul automatique vérifié"`.
---
### Task 5 : les tâches VS Code
**Files:**
- Create: `.vscode/tasks.json`, `tests/test_taches.py`
**Interfaces:**
- Consumes: commandes des Tasks 1 à 4.
- Produces: tâches (JSON strict, sans commentaire), chacune `"type": "shell"`, lancée depuis la racine du dépôt sous WSL :
| Libellé | Commande |
|---|---|
| `Tests` | `python3 -m unittest discover -s tests -v` |
| `Instance de test : démarrer` | `bash instance-de-test/demarrer.sh '${input:motDePasse}'` |
| `Instance de test : préparer` | `python3 -I instance-de-test/preparer.py '${input:motDePasse}'` |
| `Instance de test : effacer` | `docker compose -p ldtest down -v` (avec `${input:confirmation}`) |
| `Instance de test : brancher sur Ollama` | `configurer_ia.py … http://ollama:11434/v1 bge-m3:567m` (clé Anthropic lue dans `.env`) |
| `Instance de test : essai des brouillons` | `python3 -I instance-de-test/essayer_brouillons.py '${input:motDePasse}'` |
| `Ollama : construire` | `docker compose -f ollama/compose.yml build` |
| `Ollama : lancer (instance de test)` | `RESEAU_LIBREDESK=ldtest_libredesk docker compose -f ollama/compose.yml -f ollama/compose.reseau.yml up -d` |
| `Ollama : vérifier` | `python3 ollama/verifier.py http://127.0.0.1:11434/v1` |
| `Import : simulation (instance de test)` | charge `instance-de-test/.env`, `python3 -m base_connaissances.importer` |
| `Import : ÉCRIRE (instance de test)` | idem `--ecrire` |
| `Import : simulation (PRODUCTION)` | charge `.env` (clés admin), `LIBREDESK_URL='${input:urlProduction}'`, sans `--ecrire` |
| `Import : ÉCRIRE (PRODUCTION)` | idem, `--ecrire`, seulement si `${input:confirmationProduction}` vaut `oui` |
Entrées : `motDePasse` (`promptString`, `password: true`, défaut `TestAdmin-2026!`) ; `urlProduction` (`promptString`, **sans défaut**) ; `confirmation` et `confirmationProduction` (`pickString`, options `non`, `oui`, défaut `non`). La commande teste la confirmation (`[ "${input:…}" = oui ] || { echo "annulé"; exit 1; }`).
- [ ] **Step 1 : Écrire `tests/test_taches.py`** (lit `.vscode/tasks.json` avec `json`) :
```python
def test_json_valide_et_libelles_uniques(self): ...
def test_ecriture_production_demande_confirmation(self): # Review Focus 3
# toute tâche dont la commande contient --ecrire ET urlProduction teste ${input:confirmationProduction} = oui
def test_url_production_sans_defaut(self):
# l'entrée urlProduction n'a pas de clé "default"
def test_taches_instance_de_test_ne_visent_pas_la_production(self):
# aucune tâche « (instance de test) » ne référence urlProduction
def test_scripts_references_existent(self):
# chaque chemin instance-de-test/*.py|.sh, ollama/*.py, ollama/*.yml cité existe
```
- [ ] **Step 2 : Lancer, vérifier l'échec.** Run : `python3 -m unittest tests.test_taches -v`. Expected : FAIL (fichier absent).
- [ ] **Step 3 : Écrire `.vscode/tasks.json`.**
- [ ] **Step 4 : Tests verts.** Run : `python3 -m unittest discover -s tests -v`. Expected : tous PASS.
- [ ] **Step 5 : Essai dans VS Code** (WSL) : lancer `Tests`, puis `Import : simulation (instance de test)`. Expected : mêmes sorties qu'en ligne de commande ; `Import : ÉCRIRE (PRODUCTION)` avec `non` → « annulé ».
- [ ] **Step 6 : Commit** — `git add .vscode tests/test_taches.py && git commit -m "Tâches VS Code : tests, instance de test, Ollama, import (production avec confirmation)"`.
---
### Task 6 : la documentation et les gestes de production
**Files:**
- Create: `README.md` (remplace le fichier vide), `docs/production.md`
- Modify: `docs/verifications.md`
- [ ] **Step 1 : `README.md`** : à quoi sert le dépôt (le brouillon dans LibreDesk, Ollama) ; que Support-AI est archivé et n'est plus suivi ; « rien ne part chez un client » ; installation (`python3`, Docker, aucun paquet Python) ; les tâches VS Code ; les commandes équivalentes ; retoucher la base (corpus → import simulation → `--ecrire`) ; liens vers le design, `docs/production.md`, `docs/verifications.md`.
- [ ] **Step 2 : `docs/production.md`**, repris de `~/Support-AI/docs/production-libredesk-natif.md` : les gestes déjà faits restent cochés avec leur date (0 bis, 0 ter, 1 provisoire, 2, 3, 4, 5) ; le point 0 (relecture des 9 extraits « Savoir métier AIMsight ») reste ouvert ; le point « Plus tard : le programme Python sur Gitea » est retiré (abandonné le 2026-11-12). Puis la partie **Ollama**, étapes 3.1 à 3.7 du design (§6), chacune avec sa commande et sa vérification :
- 3.1 état des lieux, sans rien changer : `docker version`, `id` (groupe `docker`), `uname -m` (doit être `x86_64`), `docker ps --format '{{.Names}} {{.Image}} {{.Networks}}'`, `ip -brief addr`, `free -h`, `df -h /var/lib/docker`, `ss -ltnp`, la configuration de Caddy en lecture. **Point d'arrêt** et ses cas (design §5).
- 3.2 récupérer l'image (`docker pull` depuis le registre, ou repli `docker save … | ssh … docker load`), copier `ollama/compose.yml` (et `compose.reseau.yml` si LibreDesk est dans Docker), lancer avec `OLLAMA_BIND=<adresse interne>` ou `RESEAU_LIBREDESK=<réseau de LibreDesk>`.
- 3.3 `verifier.py` depuis l'hôte ou le réseau de LibreDesk ; depuis un téléphone en 4G, `http://46.14.212.91:11434` ne répond pas.
- 3.4 Admin → IA → Providers, Embeddings : valeurs des Global Constraints ; bouton de test, puis enregistrement.
- 3.5 journaux de LibreDesk : « reconciled embeddings … reindexed 118 ».
- 3.6 « Generate reply » sur une vraie conversation, ne rien envoyer.
- 3.7 LM Studio n'est plus nécessaire.
- Retour en arrière ; « Au quotidien » (Ollama arrêté = brouillons sans base, sans alerte : `docker ps`, `verifier.py`) ; faiblesses connues reprises (sans celles qui concernent `generer.py` ou le programme Python).
- [ ] **Step 3 : `docs/verifications.md`** : y ajouter, au-dessus de la simulation (Task 4), les constats LibreDesk encore utiles repris de Support-AI (authentification, routes des extraits et de la configuration IA, `generate-reply` sans notes privées, assistants exclus, recalcul automatique avec les références au code v2.9.0, l'essai LM Studio du 2026-11-11 et le réseau WSL `mirrored`).
- [ ] **Step 4 : Relecture croisée.** Run : `grep -rn "support_diagnostic\|Agent IA\|tri:diagnostic\|generer.py" README.md docs/production.md docs/verifications.md`. Expected : aucune occurrence, sauf la mention « abandonné » dans `production.md`.
- [ ] **Step 5 : Tests.** Run : `python3 -m unittest discover -s tests -v`. Expected : tous PASS.
- [ ] **Step 6 : Commit** — `git add README.md docs && git commit -m "Documentation : README, gestes de production avec Ollama, constats"`.
@@ -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`.