Files

T

Master 5301f79359 docs: README a jour - plan compact, prefixes f:/d:, /coller

2026-06-22 12:57:44 +02:00

13 KiB

Raw Permalink Blame History

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.py sur 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

13 KiB Raw Permalink Blame History Unescape Escape