agora-ai/README.md

# Project Agora

## Description

Project Agora est une plateforme web permettant à plusieurs intelligences artificielles de **collaborer** pour concevoir une architecture logicielle complète à partir d'une **description de projet** et optionnellement d'une **documentation contexte**.

L'objectif est de produire :

- Une **architecture logicielle complète**, incluant :
  - Une **hiérarchie de fichiers** structurée pour le projet
  - Une **spécification détaillée** du contenu attendu pour chaque fichier (sans implémentation de code, uniquement une description fonctionnelle et technique)
- Un **raisonnement justifié** pour chaque choix technique.
- Des **diagrammes explicatifs** (Mermaid).
- Une **synthèse finale cohérente** prête à être utilisée comme base de développement.

Aucune génération de code direct n'est effectuée : seules des **explications, réflexions et structures** sont produites.

---

## Objectif

Reproduire une **table ronde d'IA spécialistes**, avec un nombre d'agents flexible et configurable :

- **Agents dynamiques** (3-50) avec des noms aléatoires pour la diversité
- Chaque agent à une perspective unique sur l'architecture logicielle
- Les agents se spécialisent naturellement dans différents domaines

L'aspect le plus crucial de ces IA réside dans leur capacité à **collaborer itérativement** pour améliorer collectivement la spécification architecturale. Le processus s'arrête naturellement quand **tous les agents convergent** (plus aucune amélioration n'est proposée sur N tours consécutifs).

---

## Exemple d'utilisation

L'utilisateur entre ceci dans l'interface :

> « Je souhaite faire une application de calculatrice scientifique responsive web. »

Le système demande alors à plusieurs IA leur point de vue sur :

- Le langage ou framework le plus adapté
- L'organisation du projet (folders, modules)
- Les fichiers essentiels
- Les interactions front/back éventuelles
- Le design minimal (UI/UX conceptuel)

Elles discutent pour converger vers un consensus, puis produisent une **fiche conceptuelle du projet** au format structuré (JSON + affichage visuel + diagrammes Mermaid).

---

## Architecture technique

### Stack principal

- **Frontend**: Vue.js 3 + Vite
- **Backend**: Node.js + Express
- **AI Layer**: Multi-agent système avec Mistral API (mistral-large-2411)
- **Storage**: SQLite pour persistance complète
- **Real-time**: WebSocket pour streaming temps réel des modifications
- **Design**: Glassmorphism avec animations fluides

### Architecture globale

```mermaid
graph TD
    A[Frontend: Vue.js 3] -->|User Prompt| B[Backend: Node.js]
    B -->|Orchestration| C[AI Layer: Mistral Agents]
    C -->|Debate Data| D[Storage: SQLite/JSON]
    C -->|Diagram Specs| E[Mermaid Engine]
    E -->|SVG/Render| A
    D -->|History| A
```

---

## Fonctionnalités

### Conception Collaborative par IA

- **N agents dynamiques** (3-50) : Nombre configurable pour chaque session
- **Noms aléatoires** : Chaque agent a un nom unique pour meilleure clarté
- **Création itérative** : SYSTEM crée la structure de base
- **Tours de table automatiques** : Chaque agent revoit et peut modifier une section
- **Document évolutif** : Amélioration progressive à chaque passage
- **Opérations supportées** : Modification, création, ou suppression de sections
- **Convergence naturelle** : Arrêt automatique quand N agents de suite ne proposent aucun changement
- **Traçabilité complète** : Historique de toutes les modifications avec agent, raison, et round
- **Format Markdown** : Output toujours en Markdown (.md)
- **Context files** : Support d'upload de fichiers MD/TXT en entrée (optionnel)
- **Session discovery** : Accès facile aux sessions précédentes avec filtres et stats
- **Real-time visualization** : Observation des changements en direct via WebSocket

### Système multi-agents IA
- **Intégration Mistral AI** (mistral-large-2411) pour génération intelligente et contextualisée
- **System prompts intelligents** : Prompt générique paramétré par agent
- **Contexte intelligent** : Les agents voient le document actuel et sa version antérieure
- **Section-based editing** : Les agents modifient une section à la fois pour cohérence

### Interface et visualisation
- **Saisie de prompt** décrivant le projet souhaité
- **Upload optionnel** de fichiers contexte (MD/TXT)
- **Sélection dynamique** du nombre d'agents (3-50)
- **Visualisation en temps réel** des modifications via WebSocket
- **Timeline interactive** montrant chaque round et les agents ayant participé
- **Raised hand animation** montrant l'agent actuel qui réfléchit/modifie
- **Affichage interactif** du document Markdown avec syntaxe colorée
- **Session discovery** avec stats (complétées, en cours, total)
- **Filtres par statut** pour accéder facilement aux sessions
- **Historique des sessions** accessible depuis la page d'accueil

### Architecture et stockage
- **API REST** pour gestion des sessions collaboratives
- **WebSocket** pour streaming temps réel des modifications d'agents
- **Base SQLite** pour persistance des sessions, versions et historique complet
- **Versioning intelligent** : Chaque modification crée une version avec métadonnées (agent, raison, round)

---

## Démarrage rapide

### Prérequis

- Node.js 18+
- Clé API Mistral AI ([obtenir ici](https://console.mistral.ai/))

### Installation

**1. Backend**
```bash
cd backend
npm install
cp .env.example .env
# Éditer .env et ajouter votre MISTRAL_API_KEY
npm start
```

**2. Frontend**
```bash
cd frontend
npm install
npm run dev
```

**3. Accéder à l'application**
- Frontend: http://localhost:5173
- Backend API: http://localhost:3000
- WebSocket: ws://localhost:3000

---

## Flux Utilisateur

```mermaid
sequenceDiagram
  participant User
  participant Backend
  participant Agents
  User->>Backend: Project description + optional context file
  Backend->>Agents: Lead Architect creates initial document
  Agents-->>Backend: Document v1
  Backend->>Agents: Round 1: Review and improve
  Agents-->>Backend: Updates proposed
  Backend->>Agents: Round 2-N: Review updated document
  Agents-->>Backend: More updates OR no changes
  Backend-->>User: Final Markdown document + history
```

---

## Utilisation

### Étapes

1. **Accédez à la page d'accueil** : Consultez les sessions précédentes
   - Visualisez les stats (complétées, en cours, total)
   - Filtrez par statut si nécessaire
   - Cliquez sur une session pour la reprendre
2. **Ou créez une nouvelle session** :
   - Décrivez le projet en détail
   - Ajouter un contexte (optionnel) : Upload un fichier MD ou TXT
   - Sélectionnez le nombre d'agents (3-50)
   - Lancez "Start Design Session"
3. **Observez la collaboration** :
   - Visualisez le document en temps réel
   - Consultez la timeline avec les rounds et les agents ayant participé
   - Voir l'animation "main levée" pour l'agent actuel
4. **Processus automatique** :
   - Chaque agent revoit le document
   - Peut modifier, créer, ou supprimer une section
   - Les rounds se font automatiquement
   - Le processus s'arrête quand consensus est atteint
5. **Résultat** :
   - Document Markdown téléchargeable
   - Historique complet des modifications
   - Session reste accessible pour consultation

### Exemple

Entrée:
```
Plateforme gestion projets temps réel, équipes distribuées,
gestion tâches, communication, partage fichiers, 10K+ users
```

Processus (avec 7 agents aux noms aléatoires):
- Round 1: SYSTEM crée la structure de base
- Round 2: Chaque agent revoit et propose des améliorations
- Round 3+: Itération jusqu'à convergence

Résultat: Spécification architecturale Markdown complète avec traçabilité des changements

---

## Licence

MIT License — Open-source