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