Brouillon dans LibreDesk : design et plan
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
fe884d82ba
commit
a8ef0d8f6e
2 files changed
+555
No files matched your search
@@ -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 `# <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**
|
||||
|
||||
```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 <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**
|
||||
|
||||
```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 <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")`) :
|
||||
|
||||
```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": "<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 < b</p><ul><li>un</li><li>deux</li></ul><p>Source : S</p>")
|
||||
```
|
||||
|
||||
`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 <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**
|
||||
|
||||
```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-<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**
|
||||
|
||||
```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.
|
||||
Reference in new issue
Block a user