Files
Support-AI/docs/plans/2026-11-11-libredesk-natif.md
T
2026-11-11 14:04:27 +01:00

29 KiB

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 # <titre>, ligne vide, le contenu, ligne vide, dernière ligne Source : <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 <titre> . . . . <page>, 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
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
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

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 <pdf> - (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
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 <cle>:<secret>, 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 → <p>…</p>, lignes - → <ul><li>…</li></ul>, texte échappé (html.escape), et un dernier <p>Source : …</p>.
    • @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")) :

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("&lt;", "&#60;")
    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": "<p>ancien</p>", "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, "<p>a &lt; b</p><ul><li>un</li><li>deux</li></ul><p>Source : S</p>")

tests/test_garde_fou_base.py :

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
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 <mot de passe System> <url des embeddings> <modèle d'embeddings>, 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://<adresse>: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://<adresse>:1234/v1 <modèle> 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

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-<AAAA-MM-JJ>.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-<nom>@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

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
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.