From a8ef0d8f6efc50713d7eeeb2f1692b24309ad782 Mon Sep 17 00:00:00 2001 From: maxime Date: Wed, 11 Nov 2026 14:04:27 +0100 Subject: [PATCH] Brouillon dans LibreDesk : design et plan Co-Authored-By: Claude Opus 5.5 --- docs/plans/2026-11-11-libredesk-natif.md | 427 ++++++++++++++++++ .../2026-11-11-libredesk-natif-design.md | 128 ++++++ 2 files changed, 555 insertions(+) create mode 100644 docs/plans/2026-11-11-libredesk-natif.md create mode 100644 docs/superpowers/specs/2026-11-11-libredesk-natif-design.md diff --git a/docs/plans/2026-11-11-libredesk-natif.md b/docs/plans/2026-11-11-libredesk-natif.md new file mode 100644 index 0000000..7116609 --- /dev/null +++ b/docs/plans/2026-11-11-libredesk-natif.md @@ -0,0 +1,427 @@ +# Le brouillon de réponse dans LibreDesk : plan d'implémentation + +> **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 :** « Générer une réponse » de LibreDesk rédige un brouillon fondé sur la FAQ, le manuel, le savoir métier AIMsight et l'historique du client ; essayé sur l'instance de test avec LM Studio, puis mis en production avec Ollama. + +**Architecture :** rien n'est ajouté à LibreDesk. Ce dépôt fournit un **corpus** d'extraits relus (fichiers Markdown versionnés, produits une fois depuis les PDF et les documents de `~/Support-Agent`), les **instructions communes** (un fichier), un **script d'import idempotent** qui pousse le corpus dans la base de connaissances par l'API (`/api/v1/ai/snippets`), et deux scripts pour l'instance de test : la configuration de l'IA, puis l'essai des brouillons. La production se fait à la main, point par point, avec l'accord de Maxime. + +**Tech Stack :** Python ≥ 3.12, bibliothèque standard (urllib, unittest, http.server) ; `pdftotext` (poppler, sous WSL) pour la génération ponctuelle du corpus ; LibreDesk v2.9.0 ; LM Studio puis Ollama, modèle d'embeddings bge-m3. + +**Spec :** `docs/superpowers/specs/2026-11-11-libredesk-natif-design.md`. + +## Global Constraints + +- **Rien ne part chez un client sans qu'un humain l'ait relu et envoyé.** Aucun code de ce plan n'écrit dans une conversation, sauf la préparation de l'instance de test (où Mailpit piège tout). +- Le nouveau paquet `base_connaissances/` ne parle à LibreDesk que par `/api/v1/ai/snippets` : jamais `/messages`, `/conversations`, `/automations`, `/ai/assistants`. +- Simulation par défaut : l'import n'écrit qu'avec `--ecrire` (même logique que `DRY_RUN` dans `support_diagnostic`). +- L'import ne supprime jamais un extrait de LibreDesk : un extrait présent dans LibreDesk et absent du corpus est **signalé**, pas effacé. +- Le corpus ne contient ni noms de stations, de lieux ou de clients, ni commandes d'outils (`python3`, `agent-tools/`, `.py`), ni seuils provisoires, ni prénom interne (`Marc`). Stations connues (`~/Support-Agent/data/`, 2026-11-11) : BREITHORN, CLARIDEN, FLORIDA, JUNGFRAU, LENZSPITZE, MICHIGAN, NADELHORN, NEBRASKA, NIEDERHORN, NORDEND, SNCF01, SUSTENHORN, WILDSTRUBEL ; plus VERMONT (citée dans les guides). +- Hors de la première version (décision de Maxime) : les guides de lecture, les fiches d'incident `events/`, les cas annotés, `incident-de-barcelone.md`, les PDF « Mur de soutènement ». +- Embeddings : bge-m3, au format OpenAI. Complétion : `claude-sonnet-5-5`, `base_url` `https://api.anthropic.com/v1`, fournisseur `openai`, `max_tokens` 4096 au départ. +- Ne jamais modifier le code de LibreDesk ; ne jamais créer de règle d'automatisation ; ne jamais activer un assistant. +- Toute modification de la production : présentée à Maxime, faite seulement avec son accord explicite, un point à la fois. +- Code et documents en français, comme le reste du dépôt. +- Les commandes `python` et `git` se lancent sous WSL (Ubuntu), depuis `~/Support-AI` (le git de Windows refuse le dépôt : « dubious ownership »). Tests : `.venv/bin/python -m unittest discover -s tests -v`. + +## Review Focus + +- **Un mail en allemand** : le brouillon doit être en allemand, appuyé sur la FAQ anglaise. Essai : un mail allemand dans les mails de test (Tâche 5). +- **Une question que la base ne couvre pas** : le brouillon demande des précisions ou dit qu'on regarde, sans inventer de procédure ni de délai. Essai : un mail hors base (Tâche 5). +- **L'import rejoué après une retouche du corpus** : pas de doublon, l'extrait est mis à jour. Test : `test_rejouer_ne_cree_pas_de_doublon`, `test_contenu_change_met_a_jour` (Tâche 3). +- **Un extrait renommé ou retiré du corpus** : l'ancien reste dans LibreDesk et il est signalé, rien n'est effacé. Test : `test_extrait_inconnu_signale_pas_supprime` (Tâche 3). +- **Le service d'embeddings arrêté** (LM Studio fermé, Ollama tombé) : « Générer une réponse » doit encore rendre un brouillon ou une erreur claire, jamais un envoi. Essai : relancer un brouillon LM Studio arrêté et noter le comportement dans `docs/verifications.md` (Tâche 5). + +## Fichiers + +| Fichier | Rôle | +|---|---| +| `base_connaissances/__init__.py` | paquet vide | +| `base_connaissances/decoupage.py` | du texte d'un PDF ou d'un Markdown aux extraits (`Extrait`) ; écriture et lecture du corpus | +| `base_connaissances/generer.py` | génération ponctuelle du corpus depuis `~/Support-Agent` et `agents/knowledge/` (lancé à la main, pas en CI) | +| `base_connaissances/corpus/*.md` | le corpus relu, un fichier par extrait | +| `base_connaissances/instructions.md` | le texte des instructions communes de LibreDesk | +| `base_connaissances/importer.py` | le client restreint aux extraits et la synchronisation | +| `tests/test_decoupage.py`, `tests/test_corpus.py`, `tests/test_importer.py`, `tests/test_garde_fou_base.py` | tests | +| `instance-de-test/preparer_ia.py` | configure l'IA de l'instance de test et crée la clé d'import | +| `instance-de-test/essayer_brouillons.py`, `instance-de-test/mails/*.txt` | l'essai des brouillons | +| `docs/production-libredesk-natif.md` | la liste des gestes en production | +| `README.md`, `docs/verifications.md` | à compléter | + +--- + +### Task 1 : le découpage en extraits + +**Files :** +- Create : `base_connaissances/__init__.py`, `base_connaissances/decoupage.py` +- Test : `tests/test_decoupage.py` + +**Interfaces :** +- Produces : + - `@dataclass(frozen=True) class Extrait: titre: str; contenu: str; source: str` ; `cle` (propriété) : le nom de fichier, `slug(titre)` + `.md`. + - `decouper_pdf(texte: str, parasites: list[str]) -> list[Extrait]` : le texte brut de `pdftotext` (sans `-layout`) en extraits, un par entrée de la table des matières qui a un corps. + - `decouper_markdown(texte: str, source: str, max_car: int = 6000) -> list[Extrait]` : un extrait par fichier ; s'il dépasse `max_car`, un par section `## ` (titre : « titre du document — titre de section »). + - `ecrire_corpus(extraits: list[Extrait], dossier: Path) -> None` et `lire_corpus(dossier: Path) -> list[Extrait]`. Format d'un fichier : ligne 1 `# `, ligne vide, le contenu, ligne vide, dernière ligne `Source : `. `lire_corpus(ecrire_corpus(x))` rend `x`, triés par `cle`. + +L'algorithme de `decouper_pdf` (les tests ne le fixent pas tout à fait) : +1. La table des matières : les entrées de la forme ` . . . . `, plusieurs pouvant être collées sur une ligne (regex sur `(.+?)\s(?:\.\s?){3,}\s*\d+`), un titre pouvant continuer sur la ligne suivante (le manuel et la FAQ en ont). +2. Le corps commence après la dernière entrée de la table. On retire les lignes parasites : celles égales à un élément de `parasites` (par ex. `Revision 1.5`, `AIMsight FAQ`, `AIMsight Station Guide`) et celles faites seulement d'un nombre (les pages). +3. Un titre de la table, seul sur sa ligne dans le corps, ouvre une section qui court jusqu'au titre suivant. Une section sans texte (les titres de chapitre) ne donne pas d'extrait. +4. Le caractère de puce `�` (« � ») et les espaces qui l'entourent (`\s*�\s*`) deviennent un retour à la ligne suivi de `- `. + +- [ ] **Step 1 : écrire les tests qui échouent** + +```python +TOC = ("Contents\nInstall . . . . . . 1\n Does it start? . . . . . 1\n How long does the\n battery last? . . . . 2\n" + "Data . . . . 3 Which formats? . . . . 3\n") +CORPS = ("Install\nDoes it start?\nCheck power.\nRevision 1.5\n2\nAIMsight FAQ\nCheck fuse.\n" + "How long does the battery last?\nAbout 3 days: � sun; � mains.\nData\nWhich formats?\nCSV.\n") + +def test_un_extrait_par_question_avec_corps(self): + x = decouper_pdf(TOC + CORPS, ["Revision 1.5", "AIMsight FAQ"]) + self.assertEqual([e.titre for e in x], ["Does it start?", "How long does the battery last?", "Which formats?"]) + +def test_parasites_et_numeros_de_page_retires(self): + x = decouper_pdf(TOC + CORPS, ["Revision 1.5", "AIMsight FAQ"]) + self.assertEqual(x[0].contenu, "Check power.\nCheck fuse.") + +def test_puces(self): + self.assertIn("\n- sun;\n- mains.", decouper_pdf(TOC + CORPS, [])[1].contenu) + +def test_markdown_court_un_extrait(self): + x = decouper_markdown("# Le cycle thermique\n\nLe jour, ...\n", "labeling/connaissances/cycle-thermique.md") + self.assertEqual([(e.titre, e.source) for e in x], [("Le cycle thermique", "labeling/connaissances/cycle-thermique.md")]) + +def test_markdown_long_par_section(self): + texte = "# Doc\n\n## A\n\n" + "a" * 4000 + "\n\n## B\n\n" + "b" * 4000 + "\n" + self.assertEqual([e.titre for e in decouper_markdown(texte, "x.md")], ["Doc — A", "Doc — B"]) + +def test_aller_retour_du_corpus(self): # dans un tempfile.TemporaryDirectory + x = [Extrait("Which formats?", "CSV.", "AIMsight FAQ, rév. 1.5")] + ecrire_corpus(x, d) + self.assertEqual(lire_corpus(d), x) + self.assertEqual((d / "which-formats.md").read_text().splitlines()[-1], "Source : AIMsight FAQ, rév. 1.5") +``` + +- [ ] **Step 2 : les lancer, ils échouent** + +Run : `.venv/bin/python -m unittest tests.test_decoupage -v` +Expected : FAIL, `ModuleNotFoundError: No module named 'base_connaissances'` + +- [ ] **Step 3 : implémenter `base_connaissances/decoupage.py`** selon les interfaces et l'algorithme ci-dessus. `slug` : minuscules, accents retirés (`unicodedata`), tout ce qui n'est pas `[a-z0-9]` devient `-`, tirets en double et en bord retirés. + +- [ ] **Step 4 : les tests passent** + +Run : `.venv/bin/python -m unittest tests.test_decoupage -v` +Expected : OK + +- [ ] **Step 5 : commit** + +```bash +git add base_connaissances/__init__.py base_connaissances/decoupage.py tests/test_decoupage.py +git commit -m "Base de connaissances : découper PDF et Markdown en extraits" +``` + +--- + +### Task 2 : le corpus et les instructions communes + +**Files :** +- Create : `base_connaissances/generer.py`, `base_connaissances/corpus/*.md`, `base_connaissances/instructions.md` +- Test : `tests/test_corpus.py` + +**Interfaces :** +- Consumes : `decouper_pdf`, `decouper_markdown`, `ecrire_corpus`, `lire_corpus` (Tâche 1). +- Produces : le dossier `base_connaissances/corpus/` (lu par la Tâche 3) et `base_connaissances/instructions.md` (lu par la Tâche 4). + +Sources (spec §6), avec `SA = ~/Support-Agent` : +- `SA/docs/aimsight/AIMsight FAQ.pdf`, source `AIMsight FAQ, rév. 1.5` ; parasites `Revision 1.5`, `AIMsight FAQ`. +- `SA/docs/aimsight/AIMsight Test Manual.pdf`, source `AIMsight Station Guide, rév. 1.5` ; parasites `Revision 1.5`, `AIMsight Station Guide`. Laisser de côté *Safety and Regulatory Information* et ses sous-sections. +- Markdown : `SA/docs/domaine/*.md`, `SA/docs/displacement/domaine/ce-que-regarde-le-client.md`, `SA/docs/energy/domaine/*.md` sauf `cas-annotes-par-l-expert.md`, `SA/labeling/connaissances/*.md` sauf `cas-annotes-par-l-expert.md` et `incident-de-barcelone.md`, et `agents/knowledge/analyste/familles.md` de ce dépôt. Source : le chemin relatif au dépôt d'origine. + +- [ ] **Step 1 : écrire `tests/test_corpus.py`, qui échoue tant que le corpus n'existe pas** + +```python +CORPUS = Path(__file__).resolve().parents[1] / "base_connaissances" / "corpus" +STATIONS = ["BREITHORN", "CLARIDEN", "FLORIDA", "JUNGFRAU", "LENZSPITZE", "MICHIGAN", "NADELHORN", "NEBRASKA", + "NIEDERHORN", "NORDEND", "SNCF01", "SUSTENHORN", "WILDSTRUBEL", "VERMONT"] +INTERDITS = ["python3", "agent-tools", ".py", "Marc", "Barcelone", "Vaud", "GN-1", "GN-5", "seuil provisoire", + "seuils provisoires"] + +def test_corpus_present(self): + self.assertGreaterEqual(len(lire_corpus(CORPUS)), 60) + +def test_titres_uniques_et_contenus_non_vides(self): + x = lire_corpus(CORPUS) + self.assertEqual(len({e.titre for e in x}), len(x)) + self.assertTrue(all(e.contenu.strip() and e.source.strip() for e in x)) + +def test_taille_raisonnable(self): + self.assertTrue(all(len(e.contenu) <= 8000 for e in lire_corpus(CORPUS))) + +def test_rien_d_interne(self): + for e in lire_corpus(CORPUS): + texte = e.titre + "\n" + e.contenu + for s in STATIONS: + self.assertIsNone(re.search(rf"\b{s}\b", texte, re.I), f"{s} dans {e.cle}") + for i in INTERDITS: + self.assertNotIn(i.lower(), texte.lower(), f"{i} dans {e.cle}") + +def test_instructions_presentes(self): + texte = (CORPUS.parent / "instructions.md").read_text() + self.assertIn("langue du client", texte) + self.assertLessEqual(len(texte), 4000) +``` + +- [ ] **Step 2 : le lancer, il échoue** + +Run : `.venv/bin/python -m unittest tests.test_corpus -v` +Expected : FAIL (dossier `corpus` absent) + +- [ ] **Step 3 : implémenter `base_connaissances/generer.py`** : `main(support_agent: Path, sortie: Path) -> None`, lancé par `python -m base_connaissances.generer ~/Support-Agent base_connaissances/corpus`. Il appelle `pdftotext -` (sans `-layout`) par `subprocess.run(check=True)`, découpe les sources ci-dessus et écrit le corpus. Il refuse d'écraser un dossier `corpus` non vide (le corpus est retouché à la main après génération). + +- [ ] **Step 4 : générer, puis retoucher à la main** + +Run : `.venv/bin/python -m base_connaissances.generer ~/Support-Agent base_connaissances/corpus` +Puis relire les extraits issus des Markdown et y retirer ce que `test_rien_d_interne` signale, ainsi que les passages d'outillage interne que le test ne voit pas (références à des fichiers du projet, statuts de chantier). Ne pas réécrire le fond. + +- [ ] **Step 5 : écrire `base_connaissances/instructions.md`** à partir de `agents/knowledge/support/redaction.md` : la réponse d'abord (oui, non, ou on ne peut pas le dire, et pourquoi) ; dans la langue du client ; rien d'interne (ni outils, ni seuils, ni noms d'autres clients ou stations) ; honnête sur ce qui n'est pas établi ; phrases simples ; pas d'objet de mail, pas de pièce jointe annoncée. Rien sur `analyse.md`, le PDF ou Typst. 4000 caractères au plus. + +- [ ] **Step 6 : les tests passent** + +Run : `.venv/bin/python -m unittest tests.test_corpus -v` +Expected : OK + +- [ ] **Step 7 : commit** + +```bash +git add base_connaissances/generer.py base_connaissances/corpus base_connaissances/instructions.md tests/test_corpus.py +git commit -m "Base de connaissances : corpus relu (FAQ, manuel, savoir métier) et instructions communes" +``` + +--- + +### Task 3 : l'import idempotent + +**Files :** +- Create : `base_connaissances/importer.py` +- Test : `tests/test_importer.py`, `tests/test_garde_fou_base.py` + +**Interfaces :** +- Consumes : `Extrait`, `lire_corpus` (Tâche 1) ; `tests/faux_libredesk.py` (existant). +- Produces : + - `class Extraits: __init__(self, url: str, cle: str, secret: str, ecrire: bool)` ; `lister() -> list[dict]` (`GET /api/v1/ai/snippets`, champs `id`, `title`, `content`, `enabled`, `source`) ; `creer(e: Extrait) -> None` (`POST /api/v1/ai/snippets`) ; `modifier(id: int, e: Extrait) -> None` (`PUT /api/v1/ai/snippets/{id}`). Corps : `{"title": e.titre, "content": html(e), "enabled": True}`. Auth : en-tête `Authorization: token :`, comme `support_diagnostic/libredesk.py`. Avec `ecrire=False`, `creer` et `modifier` impriment `[simulation] …` et n'envoient rien. + - `html(e: Extrait) -> str` : paragraphes séparés par une ligne vide → `

…

`, lignes `- ` → `
  • …
`, texte échappé (`html.escape`), et un dernier `

Source : …

`. + - `@dataclass class Bilan: crees: list[str]; modifies: list[str]; inchanges: list[str]; inconnus: list[str]`. + - `synchroniser(api: Extraits, extraits: list[Extrait]) -> Bilan` : apparie par titre ; crée l'absent, modifie celui dont le contenu diffère, ne touche pas l'identique. « Identique » se juge sur le texte sans balises, entités décodées et espaces réduits à un seul (LibreDesk peut reformater le HTML qu'il enregistre) ; `inconnus` : les titres des extraits `source == "manual"` de LibreDesk absents du corpus. Jamais de `DELETE`. + - CLI : `python -m base_connaissances.importer [--ecrire]`, lit `LIBREDESK_URL`, `LIBREDESK_ADMIN_KEY`, `LIBREDESK_ADMIN_SECRET` dans l'environnement, charge `base_connaissances/corpus`, imprime le bilan. + +- [ ] **Step 1 : écrire les tests qui échouent** + +`tests/test_importer.py` (avec `FauxLibreDesk`, `LISTE = ("GET", "/api/v1/ai/snippets")`) : + +```python +def test_cree_les_absents(self): + self.faux.reponses[LISTE] = [] + b = synchroniser(self.api(), [E1, E2]) + self.assertEqual(b.crees, [E1.titre, E2.titre]) + self.assertEqual([(m, c["title"]) for m, _, c in self.faux.ecritures()], [("POST", E1.titre), ("POST", E2.titre)]) + +def test_rejouer_ne_cree_pas_de_doublon(self): + self.faux.reponses[LISTE] = [{"id": 7, "title": E1.titre, "content": html(E1), "enabled": True, "source": "manual"}] + self.assertEqual(synchroniser(self.api(), [E1]).inchanges, [E1.titre]) + self.assertEqual(self.faux.ecritures(), []) + +def test_html_reformate_reste_inchange(self): + reformate = html(E1).replace("><", ">\n<").replace("<", "<") + self.faux.reponses[LISTE] = [{"id": 7, "title": E1.titre, "content": reformate, "enabled": True, "source": "manual"}] + self.assertEqual(synchroniser(self.api(), [E1]).inchanges, [E1.titre]) + +def test_contenu_change_met_a_jour(self): + self.faux.reponses[LISTE] = [{"id": 7, "title": E1.titre, "content": "

ancien

", "enabled": True, "source": "manual"}] + synchroniser(self.api(), [E1]) + self.assertEqual(self.faux.ecritures()[0][:2], ("PUT", "/api/v1/ai/snippets/7")) + +def test_extrait_inconnu_signale_pas_supprime(self): + self.faux.reponses[LISTE] = [{"id": 9, "title": "Ancien titre", "content": "x", "enabled": True, "source": "manual"}] + b = synchroniser(self.api(), [E1]) + self.assertEqual(b.inconnus, ["Ancien titre"]) + self.assertNotIn("DELETE", [m for m, _, _ in self.faux.requetes]) + +def test_extrait_appris_ignore(self): # source "conversation" : appris par LibreDesk, pas à nous + self.faux.reponses[LISTE] = [{"id": 9, "title": "Appris", "content": "x", "enabled": True, "source": "conversation"}] + self.assertEqual(synchroniser(self.api(), [E1]).inconnus, []) + +def test_simulation_n_ecrit_rien(self): + self.faux.reponses[LISTE] = [] + synchroniser(self.api(ecrire=False), [E1]) + self.assertEqual(self.faux.ecritures(), []) + +def test_cle_envoyee(self): + self.faux.reponses[LISTE] = [] + self.api().lister() + self.assertEqual(self.faux.entetes[-1]["Authorization"], "token k:s") + +def test_html_echappe_et_listes(self): + h = html(Extrait("T", "a < b\n\n- un\n- deux", "S")) + self.assertEqual(h, "

a < b

  • un
  • deux

Source : S

") +``` + +`tests/test_garde_fou_base.py` : + +```python +AUTORISEES = {"/api/v1/ai/snippets", "/api/v1/ai/snippets/{id}"} # la route PUT s'écrit f"/api/v1/ai/snippets/{id}" + +def test_seules_les_routes_des_extraits(self): + for f in PAQUET.glob("*.py"): # PAQUET = …/base_connaissances + texte = f.read_text() + self.assertEqual(set(re.findall(r"/api/v1/[a-z0-9_/{}-]+", texte)) - AUTORISEES, set(), f.name) + for interdit in ("/messages", "/conversations", "DELETE", "automations", "assistants"): + self.assertNotIn(interdit, texte, f"{interdit} dans {f.name}") +``` + +- [ ] **Step 2 : les lancer, ils échouent** + +Run : `.venv/bin/python -m unittest tests.test_importer tests.test_garde_fou_base -v` +Expected : FAIL, `ModuleNotFoundError: No module named 'base_connaissances.importer'` + +- [ ] **Step 3 : implémenter `base_connaissances/importer.py`** selon les interfaces. Le client reprend la forme de `LibreDesk._requete` (clé envoyée seulement à l'hôte de LibreDesk, `timeout=30`) ; une erreur HTTP arrête l'import avec son code et le début de la réponse. + +- [ ] **Step 4 : tous les tests passent** + +Run : `.venv/bin/python -m unittest discover -s tests -v` +Expected : OK (`test_instance` sauté sans instance) + +- [ ] **Step 5 : commit** + +```bash +git add base_connaissances/importer.py tests/test_importer.py tests/test_garde_fou_base.py +git commit -m "Base de connaissances : import idempotent des extraits, sans suppression" +``` + +--- + +### Task 4 : l'IA de l'instance de test + +**Files :** +- Create : `instance-de-test/preparer_ia.py` +- Modify : `docs/verifications.md` (section « L'instance de test ») + +**Interfaces :** +- Consumes : `base_connaissances/instructions.md` (Tâche 2) ; la session admin comme `instance-de-test/preparer.py` (connexion `System`, cookie et en-tête CSRF). +- Produces : l'instance de test configurée ; `LIBREDESK_ADMIN_KEY` et `LIBREDESK_ADMIN_SECRET` ajoutées à `instance-de-test/.env` (lues par la Tâche 3 et la Tâche 5). + +`python -I instance-de-test/preparer_ia.py `, avec `ANTHROPIC_API_KEY` dans l'environnement : +1. `PUT /api/v1/ai/config/completion` : fournisseur `openai`, `base_url` `https://api.anthropic.com/v1`, `model` `claude-sonnet-5-5`, `max_tokens` 4096, `reasoning_effort` `medium`, `instructions` = le texte de `instructions.md`, la clé. Les noms exacts des champs : `handleUpdateAIConfig` dans `cmd/ai.go` de LibreDesk v2.9.0 et la réponse de `GET /api/v1/ai/config/completion` (relevée le 2026-11-11 : `provider`, `base_url`, `api_key`, `model`, `max_tokens`, `dimensions`, `embedding_max_tokens`, `instructions`, `reasoning_effort`, `vision`). +2. `PUT /api/v1/ai/config/embedding` : fournisseur `openai`, `base_url` = l'argument, `model` = l'argument, une clé factice non vide (`lm-studio`), `dimensions` 0 (ne pas envoyer le champ au fournisseur). +3. `POST /api/v1/ai/config/completion/test` puis `POST /api/v1/ai/config/embedding/test` : le script s'arrête sur un échec, avec la réponse. +4. Crée un agent « Import base » au rôle `Admin`, sa clé, et l'ajoute à `.env`. Ne rien créer d'autre (pas d'assistant, pas de règle). + +- [ ] **Step 1 : LM Studio.** Sur le poste de Maxime : charger bge-m3 (modèle d'embeddings), démarrer le serveur avec « Serve on Local Network ». Relever l'identifiant du modèle : `curl http://127.0.0.1:1234/v1/models` depuis Windows. + +- [ ] **Step 2 : le chemin réseau.** Depuis WSL, adresse de l'hôte Windows : `ip route show default | awk '{print $3}'` (WSL en mode NAT ; en mode « mirrored », essayer `host.docker.internal` avec `extra_hosts: ["host.docker.internal:host-gateway"]` dans le service `app`). Vérifier depuis le réseau de l'instance : + +Run : `docker run --rm --network ldtest_default curlimages/curl:8.11.1 -s http://:1234/v1/models` +Expected : le JSON de LM Studio avec bge-m3. Sinon : pare-feu Windows (autoriser le port 1234 sur le réseau de WSL), puis réessayer. + +- [ ] **Step 3 : écrire `instance-de-test/preparer_ia.py`** selon la description ci-dessus. + +- [ ] **Step 4 : le lancer sur une instance neuve** + +Run : `cd instance-de-test && docker compose -p ldtest down -v && LIBREDESK_SYSTEM_USER_PASSWORD='TestAdmin-2026!' docker compose -p ldtest up -d && cd .. && python3 -I instance-de-test/preparer.py 'TestAdmin-2026!' instance-de-test/mail-exemple.txt && python3 -I instance-de-test/preparer_ia.py 'TestAdmin-2026!' http://:1234/v1 ` +Expected : les deux tests de configuration réussis ; `.env` contient `LIBREDESK_ADMIN_KEY`. +**Si le test de la complétion échoue** : relancer avec `reasoning_effort` vide. S'il échoue encore, **s'arrêter et rapporter à Maxime** l'erreur exacte (spec §5, choix de Claude) : ne pas changer de fournisseur. + +- [ ] **Step 5 : importer le corpus** + +Run : `set -a && . instance-de-test/.env && set +a && .venv/bin/python -m base_connaissances.importer` (simulation), puis la même chose avec `--ecrire`, puis une troisième fois avec `--ecrire`. +Expected : bilan 1 et 2 : tout en `crees` ; bilan 3 : tout en `inchanges`, rien en `inconnus`. + +- [ ] **Step 6 : documenter** dans `docs/verifications.md`, section « L'instance de test » : LM Studio (serveur sur le réseau local, identifiant du modèle), l'adresse de l'hôte Windows depuis Docker, les commandes des Steps 4 et 5, le résultat des tests de configuration. + +- [ ] **Step 7 : commit** + +```bash +git add instance-de-test/preparer_ia.py docs/verifications.md +git commit -m "Instance de test : IA configurée (Claude, embeddings LM Studio) et base importée" +``` + +--- + +### Task 5 : l'essai des brouillons + +**Files :** +- Create : `instance-de-test/essayer_brouillons.py`, `instance-de-test/mails/*.txt` +- Modify : `docs/verifications.md` + +**Interfaces :** +- Consumes : l'instance de la Tâche 4 et `instance-de-test/.env`. +- Produces : un rapport `cases/essai-brouillons-.md` (hors de git, `cases/` est ignoré) que Maxime juge. + +Les mails de test (`instance-de-test/mails/`, un fichier par mail, ligne 1 l'objet, puis le corps ; inventés ou anonymisés, sans nom réel) : au moins +- `4g.txt` : la station tourne mais ne se connecte pas en 4G (FAQ) ; +- `cible-perdue.txt` : une cible n'est plus mesurée (FAQ) ; +- `fuseau.txt`, **en allemand** : quel fuseau horaire pour les horodatages de l'export (FAQ) ; +- `hors-base.txt` : une question que la base ne couvre pas (par ex. une facture) ; +- `suite.txt` : la suite d'un échange, d'un contact qui a déjà une conversation (`histoire.txt` : sa question précédente et la réponse de l'agent). + +`python -I instance-de-test/essayer_brouillons.py` : +1. Relève le nombre de messages de Mailpit (`GET http://127.0.0.1:9125/api/v1/messages`, champ `total`). +2. Crée, par la session `System` comme `preparer.py`, une conversation par mail (contact `client-@example.com`), et pour `suite.txt` la conversation `histoire.txt` d'abord, avec la réponse de l'agent (elle va dans Mailpit), au même contact. +3. Relève à nouveau le total de Mailpit (après la mise en place). +4. Pour chaque conversation de mail, appelle `POST /api/v1/ai/generate-reply` avec `{"conversation_uuid": …, "instruction": ""}` et la clé d'import ; si la réponse n'est pas `completed` (un outil attend une approbation), le noter tel quel. +5. Vérifie que le total de Mailpit **n'a pas bougé** depuis le point 3 ; sinon, s'arrêter avec une erreur « un message est sorti ». +6. Écrit le rapport : pour chaque mail, l'objet, le mail, le brouillon, la durée. + +- [ ] **Step 1 : écrire les mails de test** listés ci-dessus. + +- [ ] **Step 2 : écrire `instance-de-test/essayer_brouillons.py`** selon la description ci-dessus. + +- [ ] **Step 3 : le lancer** + +Run : `python3 -I instance-de-test/essayer_brouillons.py` +Expected : un rapport écrit, et Mailpit inchangé pendant la génération. + +- [ ] **Step 4 : les cas limites, à la main dans l'interface** (`http://127.0.0.1:9100`) : sur une conversation, cliquer sur « Générer une réponse », vérifier que le brouillon arrive dans l'éditeur et que rien n'est envoyé ; ouvrir le panneau copilot et lui demander l'historique du client ; fermer LM Studio, relancer un brouillon et noter ce qui se passe. + +- [ ] **Step 5 : faire juger le rapport par Maxime.** Critères (spec §8) : envoyable après relecture et retouches légères ; appuyé sur la FAQ ou le manuel quand la question s'y prête, et sur l'échange précédent pour `suite.txt` ; dans la langue du client ; rien d'interne ; rien d'inventé ; pas coupé. Retoucher `instructions.md`, le corpus ou `max_tokens` selon ses remarques, réimporter, relancer, jusqu'à son accord. + +- [ ] **Step 6 : documenter** dans `docs/verifications.md` : les résultats de l'essai, la valeur retenue pour `max_tokens`, le comportement sans embeddings. + +- [ ] **Step 7 : commit** + +```bash +git add instance-de-test/essayer_brouillons.py instance-de-test/mails docs/verifications.md base_connaissances +git commit -m "Instance de test : essai des brouillons jugé par Maxime" +``` + +--- + +### Task 6 : la production + +**Files :** +- Create : `docs/production-libredesk-natif.md` +- Modify : `README.md` + +**Interfaces :** +- Consumes : le corpus, `instructions.md`, l'import (Tâches 2 et 3) ; la valeur de `max_tokens` retenue (Tâche 5). + +**Ne commence qu'après l'accord de Maxime sur l'essai (Tâche 5, Step 5).** Chaque geste en production est présenté à Maxime et fait seulement avec son accord explicite. + +- [ ] **Step 1 : écrire `docs/production-libredesk-natif.md`**, la liste des gestes, chacun avec ce qu'on vérifie après : + 1. Ollama et bge-m3 sur le serveur (par la personne qui gère le serveur) : le port d'Ollama joignable depuis LibreDesk par une adresse interne, **jamais exposé hors du réseau interne** (Ollama n'a pas d'authentification). Vérification : `/v1/models` depuis la machine de LibreDesk. + 2. Admin → IA → Providers, Embeddings : fournisseur OpenAI, l'URL interne d'Ollama (`…/v1`), le modèle bge-m3, une clé factice ; bouton de test. + 3. Providers, Completion : `max_tokens` à la valeur retenue ; *Custom instructions* = `base_connaissances/instructions.md` ; bouton de test. + 4. Une clé d'administrateur pour l'import (un agent « Import base » au rôle Admin), import en simulation, puis `--ecrire`, puis rejoué (tout `inchanges`) ; **révoquer la clé** après. + 5. Admin → IA → Assistants : désactiver `support_assistant`. + 6. Vérifier qu'aucune règle d'automatisation n'existe (Admin → Automations) ni aucun outil IA. + 7. Sur une vraie conversation, « Générer une réponse » : le brouillon arrive dans l'éditeur ; ne rien envoyer. +- [ ] **Step 2 : compléter `README.md`** : une section courte « Le brouillon dans LibreDesk », qui dit ce que fait « Générer une réponse », où vivent le corpus et les instructions, comment réimporter, et renvoie à la spec, à ce plan et à `docs/production-libredesk-natif.md`. +- [ ] **Step 3 : commit** + +```bash +git add docs/production-libredesk-natif.md README.md +git commit -m "Production : la liste des gestes, le README" +``` + +- [ ] **Step 4 : dérouler la liste avec Maxime**, un geste à la fois, chacun après son accord ; cocher dans `docs/production-libredesk-natif.md` ce qui est fait et commit à la fin. diff --git a/docs/superpowers/specs/2026-11-11-libredesk-natif-design.md b/docs/superpowers/specs/2026-11-11-libredesk-natif-design.md new file mode 100644 index 0000000..10876dd --- /dev/null +++ b/docs/superpowers/specs/2026-11-11-libredesk-natif-design.md @@ -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 /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`.