🧺 Le Panier de l'Écusson — Planificateur de Contenu Multi-Agents

Prototype d'un système multi-agents (CrewAI + Streamlit) qui génère 5 jours de contenu éditorial pour un commerçant local, en s'appuyant sur des données réelles (météo, actualités, offres du commerçant) et une bibliothèque stricte de visuels — sans jamais inventer de fait, d'offre ou d'événement.

Sommaire

• Aperçu
• Architecture
• Installation
• Lancement
• Structure du projet
• Notre approche
• Limites connues et améliorations envisagées

Aperçu

Le commerçant (ici un primeur/épicerie fine à Montpellier) obtient chaque semaine une proposition de 5 posts réseaux sociaux, un par jour, avec :

• un texte engageant, adapté au contexte réel (météo, saison, actualité locale) ;
• un visuel choisi dans sa propre bibliothèque de photos (jamais généré ni inventé) ;
• une justification explicite du choix éditorial ;
• la possibilité d'éditer chaque texte avant validation (human-in-the-loop) ;
• un export JSON du planning validé.

Architecture

Trois agents CrewAI travaillent en séquence, chacun avec une responsabilité unique :

┌──────────────────────┐     ┌────────────────────────────┐     ┌──────────────────────────────┐
│  Agent d'Investigation│ --> │  Agent Filtre & Fact-Checker │ --> │  Agent Rédacteur & Directeur  │
│                       │     │        (Le Gardien)          │     │          Artistique           │
│  Collecte la météo    │     │  Élimine le bruit, vérifie    │     │  Rédige 5 posts, associe un   │
│  réelle (Open-Meteo)  │     │  qu'aucune info n'est         │     │  visuel STRICTEMENT issu de   │
│  et les actualités    │     │  inventée, ne garde que le    │     │  la bibliothèque fournie      │
│  locales réelles      │     │  contexte exploitable         │     │  (Pydantic output_pydantic)   │
│  (DuckDuckGo News)    │     │                               │     │                               │
└──────────────────────┘     └────────────────────────────┘     └──────────────────────────────┘

Pourquoi trois agents et pas un seul prompt ? Séparer collecte, vérification et rédaction permet d'isoler la responsabilité anti-hallucination dans un agent dédié (le Gardien), dont le seul rôle est de rejeter toute information non vérifiable — plutôt que de compter sur un prompt unique pour tout faire correctement à la fois.

Sortie structurée. La tâche finale utilise output_pydantic (modèles PlanningEditorial / PostJournalier) plutôt qu'un texte libre, pour que l'interface puisse afficher un planning fiable et exploitable sans parsing fragile.

Aucune donnée n'est inventée. Si l'outil météo ou l'outil actualités échoue ou ne retourne rien, le Gardien le signale explicitement comme "non exploitable" plutôt que de laisser le Rédacteur combler le vide — vérifié en conditions réelles lors du développement (voir capture de log dans nos notes : un échec de l'outil actualités a été correctement signalé sans qu'aucune fausse actualité ne soit inventée).

Installation

Prérequis : Python 3.10+, une clé API OpenAI valide.

git clone <url-du-dépôt>
cd ia-multiagent-merchant

python -m venv venv
# Windows
.\venv\Scripts\Activate.ps1
# macOS / Linux
source venv/bin/activate

pip install -r requirements.txt

Crée un fichier .env à la racine du projet :

OPENAI_API_KEY=ta_clé_openai

Renseigne les données du commerçant dans data/commerce.json :

{
  "nom": "Le Panier de l'Écusson",
  "type": "Épicerie fine & Primeur local",
  "ville": "Montpellier",
  "description": "Produits frais, locaux et de saison directement venus des producteurs d'Occitanie. Fromages, fruits et légumes bios, vins régionaux.",
  "offres_reelles": [
    "Arrivage hebdomadaire de melons de Lectoure à 2.50€ l'unité",
    "Sélection de vins du Pic Saint-Loup en promotion (-10% sur le domaine de l'Hortus)"
  ]
}

Place 5 visuels dans le dossier visuels/, avec exactement ces noms de fichier (liste stricte définie dans agents.py) :

visuels/
├── photo_melon.jpg
├── photo_panier.jpg
├── photo_vin.jpg
├── photo_soupe.jpg
└── photo_boutique.jpg

Lancement

streamlit run app.py

Dans l'interface : renseigne le nom du commerce et la saison (préremplis automatiquement depuis commerce.json et la date du jour), puis clique sur "🚀 Lancer la Génération". Le planning s'affiche en 5 cartes éditables ; chaque post peut être modifié et validé individuellement avant export JSON global.

Structure du projet

ia-multiagent-merchant/
├── agents.py            # Les 3 agents CrewAI, les outils (météo, actus), la sortie Pydantic
├── app.py                # Interface Streamlit (design + human-in-the-loop)
├── requirements.txt
├── .env                  # Clé API (non versionné)
├── data/
│   └── commerce.json     # Données réelles du commerçant (offres, description)
└── visuels/               # Bibliothèque stricte de 5 photos

Notre approche

L'exercice demandait explicitement de ne sélectionner que les informations "réellement utiles" et de ne jamais inventer de fait, d'offre ou d'événement. Nous avons traduit cette exigence en architecture plutôt qu'en simple consigne de prompt :

1. Séparation des responsabilités : un agent collecte, un agent filtre et vérifie, un agent rédige. Chacun a un unique rôle, ce qui rend le système plus prévisible et plus facile à corriger que "un gros prompt qui fait tout".
2. Outils réels, pas de simulation : météo Open-Meteo et actualités DuckDuckGo News, tous deux gratuits et sans clé, pour ancrer le contenu dans des données vérifiables plutôt que dans la mémoire du LLM.
3. Le Gardien comme garde-fou explicite : sa seule mission est de croiser les données collectées avec les données autorisées du commerçant (offres_reelles) et de rejeter tout le reste, y compris en signalant les échecs techniques d'outils plutôt que de les masquer.
4. Sortie structurée (Pydantic) plutôt que texte libre, pour fiabiliser l'intégration avec l'interface et permettre une validation humaine granulaire, post par post.
5. Human-in-the-loop : chaque post reste éditable et doit être validé individuellement avant export — le système propose, le commerçant décide.

Limites connues et améliorations envisagées

• Visuels de démonstration : la bibliothèque actuelle contient des photos génériques (banques d'images libres), pas les vraies photos du commerçant. En production, ce serait le catalogue photo réel, potentiellement alimenté par un upload ou un dossier partagé (Drive).
• Dépendance à un outil tiers non officiel : la recherche d'actualités s'appuie sur duckduckgo-search/ddgs, une librairie non officielle, susceptible de changer d'interface sans préavis (déjà rencontré pendant le développement — le package a été renommé). Une évolution possible serait de passer par une API d'actualités officielle et stable (NewsAPI, GDELT...).
• Pas de garantie dure contre les doublons de visuels : la consigne demande explicitement 5 visuels distincts sur 5 jours, mais rien ne bloque techniquement un LLM qui l'ignorerait occasionnellement — une validation Pydantic supplémentaire (contrainte d'unicité) pourrait le garantir strictement, au prix d'un risque d'échec de génération si le modèle ne respecte pas la contrainte du premier coup.
• Pas de persistance : chaque génération est indépendante ; aucun historique des plannings précédents n'est conservé. Une base de données légère (SQLite) permettrait de garder un historique et d'éviter de répéter les mêmes angles éditoriaux d'une semaine à l'autre.
• Un seul commerçant à la fois : l'architecture ne gère qu'un data/commerce.json unique. Passer à plusieurs commerçants nécessiterait un système multi-tenant (sélection du commerçant actif, isolation des données).
• Pas de publication automatique : le planning validé est exporté en JSON, mais rien ne le publie sur les réseaux sociaux. Une intégration API (Meta Business, Instagram Graph API...) serait la suite logique.