TalkToYourDB

Transformez n'importe quel fichier CSV en base de donnees SQLite et interrogez-la en langage naturel.

---

Fonctionnement

CSV  -->  Inference des types  -->  SQLite  -->  Question en langage naturel  -->  Reponse

1. Chargement : lecture du CSV avec auto-detection du delimiteur (, ; \t ...)
2. Inference des types : chaque colonne est analysee pour determiner le type le plus precis int > float > bool > date > datetime > str
3. Creation de la base : table SQLite generee avec les types SQL correspondants
4. Interrogation : une chaine LangChain genere le SQL, l'execute et formule une reponse en langage naturel

---

Pre-requis

• Python >= 3.13
• Poetry

Installation

git clone <url-du-repo>
cd TalkToYourDB
poetry install

Configuration

Creer un fichier .env a la racine du projet :

cp .env.example .env

Renseigner les valeurs :

# Provider : mistral (defaut) | anthropic
LLM_PROVIDER=mistral

# Cle API du provider choisi
MISTRAL_API_KEY=votre-cle-mistral
ANTHROPIC_API_KEY=sk-ant-...

# Modele (optionnel, un defaut est choisi par provider)
# LLM_MODEL=mistral-small-latest

Le fichier .env est ignore par git.

Providers disponibles

Provider	Modele par defaut	Cout
Mistral (recommande)	mistral-small-latest	Tier gratuit disponible
Anthropic	claude-sonnet-4-20250514	~$3 / $15 par M tokens

---

Utilisation

1. Charger un CSV

Placer le fichier dans data/csv/, puis :

python -m talktoyourdb load MonFichier.csv

La base sera creee dans data/db/MonFichier.db.

2. Interroger la base

python -m talktoyourdb query MonFichier.db "Combien de lignes dans la table ?"

Avec --verbose pour afficher la requete SQL et son resultat :

python -m talktoyourdb query MonFichier.db "Quels sont les 5 premiers resultats ?" -v

3. Lancer les tests

pytest test/ -v

---

Exemples

WorldCupMatches.csv

Question :

python -m talktoyourdb query WorldCupMatches.db "Quel pays a marque le plus de buts en tant qu'equipe a domicile toutes coupes du monde confondues ? Donne le top 5 avec le nombre de buts." -v

SQL genere :

SELECT home_team_name, SUM(home_team_goals) AS total_goals
FROM worldcupmatches
GROUP BY home_team_name
ORDER BY total_goals DESC
LIMIT 5;

Reponse :

1. Bresil - 360 buts
2. Argentine - 222 buts
3. Italie - 198 buts
4. Allemagne FR - 198 buts
5. Hongrie - 146 buts

NetflixMooviesTvshows.csv

Question :

python -m talktoyourdb query NetflixMooviesTvshows.db "Quel est le pays qui produit le plus de films (pas les series) sur Netflix ? Donne le top 3 avec le nombre de films et le pourcentage par rapport au total." -v

SQL genere :

SELECT country, COUNT(*) AS film_count,
       ROUND(COUNT(*) * 100.0 / (SELECT COUNT(*) FROM netflixmooviestvshows WHERE type = 'Movie'), 2) AS percentage
FROM netflixmooviestvshows
WHERE type = 'Movie'
GROUP BY country
ORDER BY film_count DESC
LIMIT 3;

Reponse :

1. Etats-Unis : 2058 films (33.57%)
2. Inde : 893 films (14.57%)
3. Non specifie : 440 films (7.18%)

---

Structure du projet

TalkToYourDB/
|-- talktoyourdb/
|   |-- __main__.py    # Point d'entree CLI (load / query)
|   |-- pipeline.py    # Orchestration loader + database
|   |-- loader.py      # Chargement CSV et inference des types
|   |-- database.py    # Creation des tables SQLite (SQLAlchemy)
|   |-- agent.py       # Chaine LangChain (generation SQL + reponse)
|-- data/
|   |-- csv/           # Fichiers CSV source
|   |-- db/            # Bases de donnees generees
|-- test/
|   |-- test_loader.py # Tests unitaires et d'integration
|-- .env.example       # Template de configuration
|-- pyproject.toml

---

Types supportes

Type Python	Type SQL	Exemples
int	INTEGER	42, -7, 0
float	FLOAT	3.14, -0.5
bool	BOOLEAN	true, false, True
datetime.date	DATE	2023-01-15, 15 Jan 2023
datetime	DATETIME	2023-01-15 14:30:00
str	VARCHAR	tout le reste

Les cellules vides sont converties en NULL.

---

Auteur

Lucien Laumont - laumontlucien@gmail.com