# AIVANOV — Assistant IA d'Analyse de Données

Interface conversationnelle pour interroger des bases de données en langage naturel, avec génération automatique de graphiques interactifs.

---

## 📁 Structure du Projet

```
vanna/
├── run_server.py                    # Point d'entrée — Lance le serveur AIVANOV
├── README_AIVANOV.md                # Ce fichier
│
├── src/vanna/                       # Code backend Python
│   ├── core/
│   │   ├── agent/agent.py           # Agent conversationnel principal
│   │   ├── workflow/default.py      # Gestionnaire de commandes (/help, /status)
│   │   ├── user/                    # Gestion des utilisateurs
│   │   └── tool/models.py           # Modèles Pydantic pour les outils
│   │
│   ├── tools/
│   │   ├── run_sql.py               # Outil d'exécution SQL
│   │   ├── visualize_data.py        # Outil de génération de graphiques
│   │   ├── export_pdf.py            # Outil d'export PDF
│   │   └── file_system.py           # Abstraction système de fichiers
│   │
│   ├── integrations/
│   │   ├── ollama/llm.py            # Connecteur Ollama (LLM)
│   │   ├── postgres/runner.py       # Connecteur PostgreSQL
│   │   └── local/                   # Stockage local (conversations, mémoire)
│   │
│   └── servers/
│       ├── fastapi/
│       │   ├── app.py               # Application FastAPI
│       │   └── routes.py            # Routes API (chat, historique, suggestions)
│       └── base/templates.py        # Template HTML de la page d'accueil
│
├── frontends/webcomponent/          # Code frontend TypeScript (Lit)
│   ├── src/
│   │   ├── components/
│   │   │   ├── vanna-chat.ts        # Composant chat principal
│   │   │   ├── vanna-status-bar.ts  # Barre de statut
│   │   │   ├── vanna-progress-tracker.ts  # Suivi des tâches
│   │   │   ├── rich-component-system.ts   # Rendu des composants riches
│   │   │   └── plotly-chart.ts      # Graphiques Plotly
│   │   │
│   │   ├── styles/
│   │   │   ├── vanna-design-tokens.ts     # Variables CSS (couleurs, espacements)
│   │   │   └── rich-component-styles.ts   # Styles des composants
│   │   │
│   │   └── services/
│   │       └── api-client.ts        # Client API (SSE, WebSocket)
│   │
│   ├── dist/                        # Build de production (généré)
│   │   └── vanna-components.js
│   │
│   └── package.json
│
└── data/                            # Données persistées
    └── conversations/               # Historique des conversations
```

---

## 🚀 Installation

### Prérequis

- **Python 3.10+**
- **Node.js 18+** (pour le build frontend)
- **PostgreSQL** avec une base de données (ex: Chinook)
- **Ollama** avec un modèle LLM (ex: gpt-oss:120b-cloud, llama3, mistral)

### 1. Dépendances Python

```bash
pip install fastapi uvicorn pydantic pandas plotly psycopg2-binary ollama reportlab
```

### 2. Dépendances Frontend

```bash
cd frontends/webcomponent
npm install
npm run build
```

### 3. Configuration

Éditez `run_server.py` pour configurer :

```python
# Modèle LLM Ollama
llm_service = OllamaLlmService(
    model="gpt-oss:120b-cloud",      # Nom du modèle Ollama
    host="http://localhost:11434",    # URL du serveur Ollama
)

# Base de données PostgreSQL
postgres_runner = PostgresRunner(
    host="localhost",
    port=5432,
    database="chinook",               # Nom de la BDD
    user="votre_user",
    password="votre_mot_de_passe",
)
```

### 4. Schéma de la base

Modifiez le `SYSTEM_PROMPT` dans `run_server.py` pour décrire votre schéma de base de données.

---

## ▶️ Lancement

```bash
python3 run_server.py
```

Le serveur démarre sur **http://localhost:8084**

---

## 🎯 Fonctionnalités

### Types de visualisations
- 🥧 **Camemberts** — Répartitions, parts de marché
- 📊 **Barres** — Comparaisons, classements
- 📈 **Courbes** — Évolutions temporelles
- 📉 **Histogrammes** — Distributions
- 🔥 **Cartes de chaleur** — Corrélations
- 🔀 **Combinés** — Multi-dimensions

### Commandes spéciales
- `/help` — Affiche l'aide
- `/status` — État du système (connexion SQL, mémoire)

### Exemples de questions
- "Fais-moi un camembert de la répartition des genres musicaux"
- "Quels sont les 10 artistes les plus vendus ? Montre un graphique en barres"
- "Évolution du chiffre d'affaires par année avec une courbe"
- "Donne-moi les ventes par pays avec des commentaires"

---

## 🔌 API Endpoints

| Endpoint | Description |
|----------|-------------|
| `POST /api/vanna/v2/chat_sse` | Chat en streaming (SSE) |
| `GET /api/aivanov/v1/history` | Historique des requêtes |
| `GET /api/aivanov/v1/suggestions` | Suggestions de questions |
| `GET /api/aivanov/v1/download/{file}` | Téléchargement de fichiers |

---

## 🛠️ Développement

### Rebuild du frontend

```bash
cd frontends/webcomponent
npm run build
```

### Mode développement frontend

```bash
npm run dev
```

### Logs du serveur

Les logs s'affichent dans le terminal. En cas d'erreur, vérifiez :
1. La connexion à Ollama (`curl http://localhost:11434/api/tags`)
2. La connexion PostgreSQL (`psql -h localhost -d chinook`)

---

## 📝 Licence

Projet interne AIVANOV.