diff --git a/README.md b/README.md new file mode 100644 index 0000000..76ac047 --- /dev/null +++ b/README.md @@ -0,0 +1,271 @@ +# 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 +```