9.6 KiB
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
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é.
# 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)
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 :
python3 facilitator_v8.py --render chemin/vers/fichier.yaml
Ce que ça fait :
- Valide le YAML contre
layouts_v2.yaml(signale les champs requis manquants ou les layouts inconnus — mais ne bloque pas le rendu). - Appelle
render_engine_v2.pysur ce fichier. - 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 :
# 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 :
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 :
python3 prompt_injection_v2.py
# puis recoller prompt_the_designer_injected_v3.md et
# prompt_the_encoder_injected_v2.md dans Mistral Studio