Initial commit
This commit is contained in:
Dom
183
aivanov_project/vanna/README_AIVANOV.md
Normal file
183
aivanov_project/vanna/README_AIVANOV.md
Normal file
@@ -0,0 +1,183 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user