272 lines
9.6 KiB
Markdown
272 lines
9.6 KiB
Markdown
# 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
|
||
```
|