13 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 (plan compact)
Pas de Markdown développé pendant la réflexion. Le Narrator travaille sur un
plan compact : une vue hiérarchique et concise (chapitres, slides
numérotées, tags core/OPT-XXX, audience cible). Au premier brief, il
produit directement cette carte.
Deux modes, par préfixe explicite — à taper au début de ton message :
| Préfixe | Mode | Effet |
|---|---|---|
f: |
FLUX | Modifications de structure (ordre, ajout, suppression de slides/chapitres). Le Narrator réaffiche le plan compact complet mis à jour, numéros recalculés. |
d: |
DEEP DIVE | Travail sur le contenu d'un point précis (message, angle, formulation d'une slide). Réponse courte et ciblée, le plan n'est pas réaffiché. |
Le mode persiste : tant que tu ne retapes pas un préfixe, le Narrator
reste dans le dernier mode utilisé. Pas besoin de répéter d: à chaque
message si tu approfondis la même slide sur plusieurs tours.
Exemples :
f: inverse les chapitres 2 et 3
f: supprime les slides 7, 9 et 11
f: ajoute une slide après la 12 sur les interdépendances entre domaines
d: sur la slide 4, le message doit insister sur le coût caché, pas la dette
d: la slide 7 est-elle au bon endroit pour cette analogie ?
Commandes disponibles à tout moment :
| Commande | Effet |
|---|---|
/lire |
Scanne inputs/, injecte les nouveaux documents dans la conversation (incrémental) |
/coller |
Mode collage multiligne — voir ci-dessous |
/formalise |
Transforme le plan compact validé en Markdown structuré complet pour le Designer |
/valider |
Valide le Markdown formalisé → passe à l'étape Designer |
/plan |
Réaffiche le dernier plan compact en entier |
/aide |
Rappelle les préfixes et les commandes |
/quitter (ou /q, /exit) |
Abandonne la session Narrator, retour au menu projet |
/coller — copier-coller multiligne sans déclencher de commandes
Un terminal lit l'entrée ligne par ligne. Si tu colles un bloc de texte
(brief préparé ailleurs, contenu d'un mail), chaque ligne du collage est
interprétée séparément — une ligne qui commence par / ou par f:/d:
au milieu de ton texte serait alors lue comme une commande ou un
changement de mode, et ton message arriverait haché.
/coller évite ça : tape la commande, colle ton bloc (même s'il contient
des / ou des f: en plein milieu), termine par une ligne contenant
uniquement un point .. Tout le bloc est lu comme un seul message brut,
sans aucune interprétation, puis envoyé dans le mode courant.
Vous : /coller
Mode collage — colle ton texte, puis une ligne avec '.' seul pour terminer :
Voici le brief reçu par mail :
/objectif principal : convaincre le CODIR
f: on pensait à une structure en 3 parties
Merci de ton avis
.
Ici, /objectif et f: on pensait... sont du texte normal, pas des
commandes — parce qu'on est en mode collage jusqu'au . final.
Persistance du plan compact
Le plan compact est sauvegardé automatiquement à chaque modification de
flux (f:), dans project_state.json. Si tu fermes le terminal sans
/valider ni /formalise, le plan n'est pas perdu : à la prochaine
ouverture du projet (menu [1] Réviser), il est rechargé à l'identique
— mêmes slides, mêmes numéros, même structure, pas de régénération.
Si tu modifies le plan après avoir formalisé un Markdown, le facilitator te signale que les deux ont diverging :
! Le plan a été modifié après la dernière formalisation — pense à
/formalise avant de générer.
Flux typique :
Vous : Deck d'onboarding data domains, 1h, modulaire
[Narrator produit le plan compact initial]
Vous : f: supprime la slide 5, elle double la 4
[plan compact réaffiché, numéros recalculés]
Vous : d: sur la slide 8, reformule le message autour de l'échelle plutôt que la valeur
[réponse ciblée, plan non réaffiché]
Vous : /lire
[injecte les nouveaux documents de inputs/]
Vous : /formalise
[Narrator produit le Markdown structuré complet]
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 |
| Avertissement « le plan a divergé » | Le plan compact a été modifié en f: après le dernier /formalise |
Retape /formalise pour regénérer un Markdown à jour avant /valider |
| Une commande tapée dans un texte collé s'est exécutée toute seule | Collage multiligne sans /coller |
Toujours utiliser /coller pour coller un bloc de texte (voir section 4) |
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