aivanov_database/aivanov_project/vanna/README_AIVANOV.md

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

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

2. Dépendances Frontend

cd frontends/webcomponent
npm install
npm run build

3. Configuration

Éditez run_server.py pour configurer :

# 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

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

cd frontends/webcomponent
npm run build

Mode développement frontend

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.