# 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 (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 : ```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 ```