184 lines
5.5 KiB
Markdown
184 lines
5.5 KiB
Markdown
# 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.
|