# 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/ / inputs/ ← tes documents de contexte (déposés manuellement) outputs/ ← tout ce que le pipeline génère __narrator.md __designer_annote.md __input.yaml __input.pptx __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//outputs/_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 ```