sliding-automation/README.md

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