docs: README facilitator - guide d'utilisation complet
This commit is contained in:
@@ -0,0 +1,271 @@
|
|||||||
|
# Sliding Pipeline — Guide d'utilisation du Facilitator
|
||||||
|
|
||||||
|
Orchestrateur du pipeline de génération automatique de présentations
|
||||||
|
Pernod Ricard. Le facilitator coordonne les agents Mistral (Narrator,
|
||||||
|
Designer, Encoder, Free Designer) et `render_engine_v2.py` pour produire
|
||||||
|
un PPTX à partir d'un brief.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd ~/App/Sliding/python-pptx
|
||||||
|
source venv/bin/activate
|
||||||
|
pip install -r requirements.txt # si besoin : python-dotenv, requests, pyyaml,
|
||||||
|
# python-pptx, pypdf, pdfplumber, python-docx
|
||||||
|
```
|
||||||
|
|
||||||
|
### Fichier `.env`
|
||||||
|
|
||||||
|
À créer à la racine (`~/App/Sliding/python-pptx/.env`), jamais commité.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Obligatoire
|
||||||
|
MISTRAL_API_KEY=xxxxxxxxxxxxxxxx
|
||||||
|
NARRATOR_AGENT_ID=ag:xxxxxxxx
|
||||||
|
DESIGNER_AGENT_ID=ag:xxxxxxxx
|
||||||
|
ENCODER_AGENT_ID=ag:xxxxxxxx
|
||||||
|
|
||||||
|
# Optionnel — active le flux libre si présent
|
||||||
|
FREE_DESIGNER_AGENT_ID=ag:xxxxxxxx
|
||||||
|
|
||||||
|
# Optionnel — valeurs par défaut indiquées
|
||||||
|
PROJECTS_DIR=./projets
|
||||||
|
RENDER_ENGINE_PATH=render_engine_v2.py
|
||||||
|
THEME_PATH=theme_v2.yaml
|
||||||
|
COMPONENTS_PATH=components_v2.yaml
|
||||||
|
LAYOUTS_PATH=layouts_v2.yaml
|
||||||
|
CONTEXT_MAX_CHARS=12000
|
||||||
|
|
||||||
|
# Optionnel — archivage Trilium en fin de génération (non bloquant si absent)
|
||||||
|
TRILIUM_API_URL=https://api-trilium.bertha-cloud.fr
|
||||||
|
TRILIUM_API_KEY=xxxxxxxxxxxxxxxx
|
||||||
|
TRILIUM_PROJET=SlidingAutomation
|
||||||
|
```
|
||||||
|
|
||||||
|
Sans `FREE_DESIGNER_AGENT_ID`, le flux libre est simplement indisponible
|
||||||
|
dans le menu — pas d'erreur bloquante.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Les deux modes de lancement
|
||||||
|
|
||||||
|
### Mode pipeline complet (par défaut)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 facilitator_v8.py
|
||||||
|
```
|
||||||
|
|
||||||
|
Lance le menu projet → Narrator → choix de flux → Designer/Free Designer
|
||||||
|
→ Encoder → rendu. C'est le mode normal, décrit en détail section 4.
|
||||||
|
|
||||||
|
### Mode `--render` — contourner le pipeline, rendre un YAML directement
|
||||||
|
|
||||||
|
**C'est la commande que tu cherches pour aller droit à la génération :**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 facilitator_v8.py --render chemin/vers/fichier.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
Ce que ça fait :
|
||||||
|
1. Valide le YAML contre `layouts_v2.yaml` (signale les champs requis
|
||||||
|
manquants ou les layouts inconnus — mais ne bloque pas le rendu).
|
||||||
|
2. Appelle `render_engine_v2.py` sur ce fichier.
|
||||||
|
3. Produit le PPTX au même endroit, même nom, extension `.pptx`.
|
||||||
|
|
||||||
|
**Aucun appel aux agents Mistral, aucune clé API consommée.** Utile pour :
|
||||||
|
- Re-rendre un YAML déjà généré après avoir corrigé le moteur (`render_engine_v2.py`)
|
||||||
|
- Tester un YAML écrit ou modifié à la main
|
||||||
|
- Déboguer un crash de rendu sans repasser par tout le pipeline conversationnel
|
||||||
|
- Itérer rapidement sur le design system sans payer de tokens
|
||||||
|
|
||||||
|
**Exemples concrets :**
|
||||||
|
```bash
|
||||||
|
# Re-rendre le YAML d'un projet existant
|
||||||
|
python3 facilitator_v8.py --render projets/data-domain-pitch-deck/outputs/data-domain-pitch-deck_20260619_190942_input.yaml
|
||||||
|
|
||||||
|
# Tester un YAML de démo
|
||||||
|
python3 facilitator_v8.py --render sliding_input_test_v2.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
Le PPTX est généré dans le même dossier que le YAML source.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Organisation par projet
|
||||||
|
|
||||||
|
Chaque présentation vit dans son propre dossier sous `PROJECTS_DIR` (défaut
|
||||||
|
`./projets`) :
|
||||||
|
|
||||||
|
```
|
||||||
|
projets/
|
||||||
|
<slug-du-projet>/
|
||||||
|
inputs/ ← tes documents de contexte (déposés manuellement)
|
||||||
|
outputs/ ← tout ce que le pipeline génère
|
||||||
|
<slug>_<timestamp>_narrator.md
|
||||||
|
<slug>_<timestamp>_designer_annote.md
|
||||||
|
<slug>_<timestamp>_input.yaml
|
||||||
|
<slug>_<timestamp>_input.pptx
|
||||||
|
<slug>_<timestamp>_manifest.json
|
||||||
|
project_state.json ← état courant (dernier markdown/yaml/pptx)
|
||||||
|
journal.md ← historique des décisions, horodaté
|
||||||
|
```
|
||||||
|
|
||||||
|
### Documents de contexte (`inputs/`)
|
||||||
|
|
||||||
|
Dépose à tout moment des fichiers dans `inputs/` : `.pdf`, `.docx`, `.pptx`,
|
||||||
|
`.txt`, `.md`, `.csv`. Au lancement du Narrator, tape la commande `/lire`
|
||||||
|
pour qu'il les scanne et les intègre à la conversation. `/lire` est
|
||||||
|
incrémental — il ne recharge pas les fichiers déjà lus.
|
||||||
|
|
||||||
|
### Reprendre un projet existant
|
||||||
|
|
||||||
|
Si tu rouvres un projet qui a déjà produit une présentation
|
||||||
|
(`project_state.json` non vide), le facilitator propose directement :
|
||||||
|
```
|
||||||
|
[1] Réviser la présentation existante
|
||||||
|
[2] Nouvelle présentation dans ce projet
|
||||||
|
[3] Poser des questions (sans rien régénérer)
|
||||||
|
```
|
||||||
|
Le Narrator est réamorcé avec le dernier Markdown + le journal — pas
|
||||||
|
besoin de tout réexpliquer.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Le pipeline pas à pas
|
||||||
|
|
||||||
|
### Étape 1 — The Narrator (conversation libre)
|
||||||
|
|
||||||
|
Pas de menu numéroté : tu écris en langage naturel. Le Narrator réfléchit
|
||||||
|
avec toi, propose des angles, pose des questions. Il ne produit le Markdown
|
||||||
|
structuré que sur demande explicite.
|
||||||
|
|
||||||
|
**Commandes slash disponibles à tout moment :**
|
||||||
|
|
||||||
|
| Commande | Effet |
|
||||||
|
|---|---|
|
||||||
|
| `/lire` (ou `/contexte`, `/docs`) | Scanne `inputs/`, injecte les nouveaux documents dans la conversation |
|
||||||
|
| `/formalise` (ou `/structure`, `/markdown`) | Demande au Narrator de produire le Markdown structuré complet |
|
||||||
|
| `/valider` | Valide le Markdown formalisé → passe à l'étape Designer |
|
||||||
|
| `/sauvegarder` | Sauvegarde le dernier message dans `outputs/` |
|
||||||
|
| `/afficher` | Réaffiche le dernier message du Narrator en entier (sans troncature) |
|
||||||
|
| `/aide` | Rappelle ces commandes |
|
||||||
|
| `/quitter` (ou `/q`, `/exit`) | Abandonne la session Narrator, retour au menu projet |
|
||||||
|
|
||||||
|
Flux typique :
|
||||||
|
```
|
||||||
|
Vous : Je dois convaincre le COMEX d'investir 400K€ en data governance
|
||||||
|
[Narrator pose des questions, propose des angles]
|
||||||
|
Vous : [discussion, affinage...]
|
||||||
|
Vous : /lire
|
||||||
|
[injecte les documents déposés dans inputs/]
|
||||||
|
Vous : /formalise
|
||||||
|
[Narrator produit le Markdown structuré]
|
||||||
|
Vous : /valider
|
||||||
|
```
|
||||||
|
|
||||||
|
### Étape 2 — Choix du flux
|
||||||
|
|
||||||
|
```
|
||||||
|
[1] Standard — layouts prédéfinis (Designer annote, Encoder, rendu)
|
||||||
|
[2] Libre — composition sur mesure (Free Designer)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Standard** : pour les présentations régulières. Le Designer reprend ton
|
||||||
|
Markdown et ajoute une annotation `@layout:` sous chaque slide — tu vois
|
||||||
|
contenu et structure dans une vue unique, et tu peux donner du feedback
|
||||||
|
("slide 4 en big_stat"). Puis l'Encoder transcrit en YAML.
|
||||||
|
|
||||||
|
**Libre** : pour les présentations stratégiques. Le Free Designer compose
|
||||||
|
directement chaque slide avec des blocs positionnés sur une grille 12×12,
|
||||||
|
en respectant la charte PR imposée (couleurs et polices fixes). Pas
|
||||||
|
d'Encoder dans ce flux — le YAML freeform est produit directement.
|
||||||
|
|
||||||
|
Si tu n'as pas configuré `FREE_DESIGNER_AGENT_ID`, l'option 2 retombe
|
||||||
|
automatiquement sur le flux standard.
|
||||||
|
|
||||||
|
### Étape 3 — Mode express (flux standard uniquement)
|
||||||
|
|
||||||
|
Juste après le choix de flux, en mode standard :
|
||||||
|
```
|
||||||
|
Mode express — sans Designer ? (o/N) :
|
||||||
|
```
|
||||||
|
`o` envoie le Markdown directement à l'Encoder, sans passer par
|
||||||
|
l'annotation du Designer. Plus rapide, moins de contrôle sur les layouts
|
||||||
|
choisis — à réserver aux présentations simples ou à un premier brouillon.
|
||||||
|
|
||||||
|
### Étape 4 — Rendu
|
||||||
|
|
||||||
|
Automatique une fois le YAML validé. Le PPTX apparaît dans `outputs/`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Réviser une présentation
|
||||||
|
|
||||||
|
Après génération, un menu apparaît :
|
||||||
|
```
|
||||||
|
[1] Réviser la présentation (repasse par le Narrator)
|
||||||
|
[2] Terminer
|
||||||
|
```
|
||||||
|
|
||||||
|
En révision, la session Narrator est conservée — il a tout le contexte du
|
||||||
|
deck. Tu retravailles ce qui doit changer, puis `/formalise` régénère le
|
||||||
|
**Markdown complet**. Ensuite tu choisis la portée :
|
||||||
|
|
||||||
|
```
|
||||||
|
[1] Ciblé — quelques slides modifiées, le reste inchangé
|
||||||
|
→ seules ces slides sont régénérées (PPTX à coller dans ton deck maître)
|
||||||
|
[2] Structurant — la logique d'ensemble a changé
|
||||||
|
→ tout le deck est régénéré
|
||||||
|
```
|
||||||
|
|
||||||
|
En mode ciblé, indique les numéros (`4, 7` ou `4-6`) — le Designer et
|
||||||
|
l'Encoder ne retraitent que ces slides, en conservant leur position réelle.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Dépannage rapide
|
||||||
|
|
||||||
|
| Symptôme | Cause probable | Action |
|
||||||
|
|---|---|---|
|
||||||
|
| `Variable .env manquante` au lancement | Clé absente du `.env` | Vérifier `MISTRAL_API_KEY` et les 3 `*_AGENT_ID` obligatoires |
|
||||||
|
| `Erreur render_engine_v2.py` après l'Encoder | YAML mal formé ou layout non géré par le moteur | Le YAML est conservé dans `outputs/` — corriger puis `--render` dessus directement |
|
||||||
|
| Option flux libre absente du menu | `FREE_DESIGNER_AGENT_ID` non défini | L'ajouter au `.env` |
|
||||||
|
| `Trilium injoignable` | Réseau ou DNS interne indisponible | Sans conséquence — l'archivage est non bloquant, le PPTX est généré normalement |
|
||||||
|
| Le Designer/Encoder boucle sur des erreurs de validation | Le plan ne respecte pas les champs requis d'un layout | Après 3 tentatives, le facilitator propose d'accepter tel quel ou de revenir en arrière |
|
||||||
|
| `/lire` ne trouve rien | Documents déjà chargés dans cette session, ou format non supporté | `/lire` est incrémental ; formats acceptés : pdf, docx, pptx, txt, md, csv |
|
||||||
|
|
||||||
|
### Re-rendre après un crash du moteur
|
||||||
|
|
||||||
|
Le réflexe le plus utile : le YAML survit toujours dans `outputs/` même si
|
||||||
|
le rendu échoue. Pas besoin de relancer tout le pipeline conversationnel :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python3 facilitator_v8.py --render projets/<projet>/outputs/<fichier>_input.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
Corrige `render_engine_v2.py` ou le YAML, relance la même commande, jusqu'à
|
||||||
|
obtenir un rendu propre.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Fichiers de configuration du design system
|
||||||
|
|
||||||
|
Ne pas modifier sans nécessité — ce sont les fondations partagées par tous
|
||||||
|
les flux :
|
||||||
|
|
||||||
|
| Fichier | Rôle |
|
||||||
|
|---|---|
|
||||||
|
| `theme_v2.yaml` | Palette, typographie, grille, style des cartes |
|
||||||
|
| `layouts_v2.yaml` | Les 21 layouts standards, leurs champs requis/optionnels |
|
||||||
|
| `components_v2.yaml` | Composants unifiés (badge, carte, bandeau d'en-tête...) |
|
||||||
|
| `render_engine_v2.py` | Le moteur de rendu — traduit YAML en PPTX |
|
||||||
|
|
||||||
|
Après toute modification de `layouts_v2.yaml`, régénérer les prompts
|
||||||
|
injectés des agents :
|
||||||
|
```bash
|
||||||
|
python3 prompt_injection_v2.py
|
||||||
|
# puis recoller prompt_the_designer_injected_v3.md et
|
||||||
|
# prompt_the_encoder_injected_v2.md dans Mistral Studio
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user