Metadata-Version: 2.4
Name: gsql
Version: 3.0.0
Summary: Complete SQL Database System in Python with AI Integration
Home-page: https://github.com/gopu-inc/gsql
Download-URL: https://github.com/gopu-inc/gsql/archive/refs/tags/v3.0.0.tar.gz
Author: Gopu Inc.
Author-email: contact@gopu-inc.com
License: MIT License
Project-URL: Homepage, https://github.com/gopu-inc/gsql
Project-URL: Documentation, https://gsql.readthedocs.io
Project-URL: Source Code, https://github.com/gopu-inc/gsql
Project-URL: Bug Tracker, https://github.com/gopu-inc/gsql/issues
Project-URL: Changelog, https://github.com/gopu-inc/gsql/releases
Keywords: sql,database,sqlite,python,ai,nlp,query,relational,data,analytics,management,server,cli,shell,indexing,storage,transaction
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Database
Classifier: Topic :: Database :: Database Engines/Servers
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: Environment :: Console
Classifier: Natural Language :: English
Classifier: Natural Language :: French
Provides: gsql
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: sqlite3
Requires-Dist: click
Requires-Dist: colorama
Requires-Dist: prompt-toolkit
Requires-Dist: rich
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: nltk
Requires-Dist: spacy
Requires-Dist: psutil
Requires-Dist: typing-extensions
Requires-Dist: cryptography
Provides-Extra: dev
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.24.0; extra == "docs"
Provides-Extra: performance
Requires-Dist: pandas>=1.5.0; extra == "performance"
Requires-Dist: numpy>=1.24.0; extra == "performance"
Requires-Dist: psutil>=5.9.0; extra == "performance"
Provides-Extra: nlp
Requires-Dist: nltk>=3.8.0; extra == "nlp"
Requires-Dist: spacy>=3.6.0; extra == "nlp"
Requires-Dist: transformers>=4.30.0; extra == "nlp"
Requires-Dist: torch>=2.0.0; extra == "nlp"
Provides-Extra: full
Requires-Dist: pandas>=1.5.0; extra == "full"
Requires-Dist: numpy>=1.24.0; extra == "full"
Requires-Dist: nltk>=3.8.0; extra == "full"
Requires-Dist: spacy>=3.6.0; extra == "full"
Requires-Dist: transformers>=4.30.0; extra == "full"
Requires-Dist: torch>=2.0.0; extra == "full"
Requires-Dist: psutil>=5.9.0; extra == "full"
Requires-Dist: prompt-toolkit>=3.0.0; extra == "full"
Requires-Dist: click>=8.0.0; extra == "full"
Requires-Dist: colorama>=0.4.0; extra == "full"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: download-url
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: platform
Dynamic: project-url
Dynamic: provides
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<img width="1024" height="1024" alt="IMG_7686" src="https://github.com/user-attachments/assets/9cf47e59-c2f3-49d9-a7c2-82771d5363bd" />

> **GSQL - Système de Base de Données SQL Complet 🚀**
> **powered by gopu.inc,**

<!-- PyPI - Python Package Index -->
[![PyPI](https://img.shields.io/pypi/v/gsql?style=for-the-badge&logo=pypi&logoColor=white&color=blue)](https://pypi.org/project/gsql/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/gsql?style=for-the-badge&logo=pypi&logoColor=white&color=orange)](https://pypi.org/project/gsql/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/gsql?style=for-the-badge&logo=python&logoColor=white&color=green)](https://pypi.org/project/gsql/)
[![PyPI - Wheel](https://img.shields.io/pypi/wheel/gsql?style=for-the-badge&logo=python&logoColor=white&color=blueviolet)](https://pypi.org/project/gsql/)
[![PyPI - Format](https://img.shields.io/pypi/format/gsql?style=for-the-badge&logo=python&logoColor=white&color=9cf)](https://pypi.org/project/gsql/)
[![PyPI - Status](https://img.shields.io/pypi/status/gsql?style=for-the-badge&logo=python&logoColor=white&color=success)](https://pypi.org/project/gsql/)

<!-- Conda -->
[![Conda](https://img.shields.io/conda/v/conda-forge/gsql?style=for-the-badge&logo=anaconda&logoColor=white&color=44A833)](https://anaconda.org/conda-forge/gsql)
[![Conda Downloads](https://img.shields.io/conda/dn/conda-forge/gsql?style=for-the-badge&logo=anaconda&logoColor=white&color=orange)](https://anaconda.org/conda-forge/gsql)
[![Conda Platform](https://img.shields.io/conda/pn/conda-forge/gsql?style=for-the-badge&logo=anaconda&logoColor=white&color=blue)](https://anaconda.org/conda-forge/gsql)

<!-- Docker Hub -->
[![Docker Pulls](https://img.shields.io/docker/pulls/gopu/gsql?style=for-the-badge&logo=docker&logoColor=white&color=2496ED)](https://hub.docker.com/r/gopu/gsql)
[![Docker Image Size](https://img.shields.io/docker/image-size/gopu/gsql/latest?style=for-the-badge&logo=docker&logoColor=white&color=blue)](https://hub.docker.com/r/gopu/gsql)
[![Docker Version](https://img.shields.io/docker/v/gopu/gsql?style=for-the-badge&logo=docker&logoColor=white&color=blueviolet)](https://hub.docker.com/r/gopu/gsql)
[![Docker Stars](https://img.shields.io/docker/stars/gopu/gsql?style=for-the-badge&logo=docker&logoColor=white&color=yellow)](https://hub.docker.com/r/gopu/gsql)

<!-- GitHub Container Registry -->
[![GitHub Container Registry](https://img.shields.io/badge/GitHub%20Container%20Registry-available-2496ED?style=for-the-badge&logo=github&logoColor=white)](https://github.com/gopu-inc/gsql/pkgs/container/gsql)
<!-- GitHub Stars & Forks -->
[![GitHub Stars](https://img.shields.io/github/stars/gopu-inc/gsql?style=for-the-badge&logo=github&logoColor=white&color=yellow)](https://github.com/gopu-inc/gsql/stargazers)
[![GitHub Forks](https://img.shields.io/github/forks/gopu-inc/gsql?style=for-the-badge&logo=github&logoColor=white&color=blue)](https://github.com/gopu-inc/gsql/network/members)
[![GitHub Watchers](https://img.shields.io/github/watchers/gopu-inc/gsql?style=for-the-badge&logo=github&logoColor=white&color=purple)](https://github.com/gopu-inc/gsql/watchers)

<!-- GitHub Issues & PRs -->
[![GitHub Issues](https://img.shields.io/github/issues/gopu-inc/gsql?style=for-the-badge&logo=github&logoColor=white&color=red)](https://github.com/gopu-inc/gsql/issues)
[![GitHub Issues Closed](https://img.shields.io/github/issues-closed/gopu-inc/gsql?style=for-the-badge&logo=github&logoColor=white&color=green)](https://github.com/gopu-inc/gsql/issues?q=is%3Aissue+is%3Aclosed)
[![GitHub Pull Requests](https://img.shields.io/github/issues-pr/gopu-inc/gsql?style=for-the-badge&logo=github&logoColor=white&color=orange)](https://github.com/gopu-inc/gsql/pulls)
[![GitHub Pull Requests Closed](https://img.shields.io/github/issues-pr-closed/gopu-inc/gsql?style=for-the-badge&logo=github&logoColor=white&color=green)](https://github.com/gopu-inc/gsql/pulls?q=is%3Apr+is%3Aclosed)

<!-- GitHub Activity -->
[![GitHub Last Commit](https://img.shields.io/github/last-commit/gopu-inc/gsql?style=for-the-badge&logo=github&logoColor=white&color=blue)](https://github.com/gopu-inc/gsql/commits/main)
[![GitHub Commit Activity](https://img.shields.io/github/commit-activity/m/gopu-inc/gsql?style=for-the-badge&logo=github&logoColor=white&color=green)](https://github.com/gopu-inc/gsql/graphs/commit-activity)
[![GitHub Contributors](https://img.shields.io/github/contributors/gopu-inc/gsql?style=for-the-badge&logo=github&logoColor=white&color=purple)](https://github.com/gopu-inc/gsql/graphs/contributors)

<!-- GitHub Size & Language -->
[![GitHub Repo Size](https://img.shields.io/github/repo-size/gopu-inc/gsql?style=for-the-badge&logo=github&logoColor=white&color=blue)](https://github.com/gopu-inc/gsql)
[![GitHub Code Size](https://img.shields.io/github/languages/code-size/gopu-inc/gsql?style=for-the-badge&logo=github&logoColor=white&color=blueviolet)](https://github.com/gopu-inc/gsql)
[![GitHub Language Count](https://img.shields.io/github/languages/count/gopu-inc/gsql?style=for-the-badge&logo=github&logoColor=white&color=orange)](https://github.com/gopu-inc/gsql)
[![GitHub Top Language](https://img.shields.io/github/languages/top/gopu-inc/gsql?style=for-the-badge&logo=python&logoColor=white&color=green)](https://github.com/gopu-inc/gsql)
<!-- Licences -->
[![License](https://img.shields.io/github/license/gopu-inc/gsql?style=for-the-badge&logo=opensourceinitiative&logoColor=white&color=yellow)](LICENSE)
[![FOSSA Status](https://img.shields.io/fossa/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fgopu-inc%2Fgsql.svg?style=for-the-badge&logo=fossa&logoColor=white&color=blue)](https://app.fossa.com/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fgopu-inc%2Fgsql)
[![License - OSI Approved](https://img.shields.io/badge/OSI%20Approved-MIT-yellow?style=for-the-badge&logo=opensourceinitiative&logoColor=white)](https://opensource.org/licenses/MIT)

<!-- Open Source Metrics -->
[![Open Source](https://img.shields.io/badge/Open%20Source-Yes-brightgreen?style=for-the-badge&logo=opensourceinitiative&logoColor=white)](https://opensource.org)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=for-the-badge&logo=git&logoColor=white)](https://github.com/gopu-inc/gsql/pulls)
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa?style=for-the-badge&logo=contributor-covenant&logoColor=white)](CODE_OF_CONDUCT.md)
<!-- Téléchargements Totaux -->
[![Total Downloads](https://img.shields.io/github/downloads/gopu-inc/gsql/total?style=for-the-badge&logo=github&logoColor=white&color=blue)](https://github.com/gopu-inc/gsql/releases)
[![Downloads](https://img.shields.io/github/downloads/gopu-inc/gsql/latest/total?style=for-the-badge&logo=github&logoColor=white&color=orange)](https://github.com/gopu-inc/gsql/releases/latest)
[![Release Downloads](https://img.shields.io/github/downloads/gopu-inc/gsql/v3.0.0/total?style=for-the-badge&logo=github&logoColor=white&color=green)](https://github.com/gopu-inc/gsql/releases/tag/v3.0.0)

<!-- PyPI Downloads Détail -->
[![PyPI - Downloads (Daily)](https://img.shields.io/pypi/dd/gsql?style=for-the-badge&logo=pypi&logoColor=white&color=lightblue)](https://pypistats.org/packages/gsql)
[![PyPI - Downloads (Weekly)](https://img.shields.io/pypi/dw/gsql?style=for-the-badge&logo=pypi&logoColor=white&color=orange)](https://pypistats.org/packages/gsql)
[![PyPI - Downloads (Monthly)](https://img.shields.io/pypi/dm/gsql?style=for-the-badge&logo=pypi&logoColor=white&color=red)](https://pypistats.org/packages/gsql)

<!-- Conda Downloads -->
[![Conda Downloads (Monthly)](https://img.shields.io/conda/dn/conda-forge/gsql?style=for-the-badge&logo=anaconda&logoColor=white&color=orange)](https://anaconda.org/conda-forge/gsql)
[![Conda Downloads (Total)](https://img.shields.io/conda/d/conda-forge/gsql?style=for-the-badge&logo=anaconda&logoColor=white&color=green)](https://anaconda.org/conda-forge/gsql)

---

## 📋 Table des Matières

1. [🚀 Vue d'Ensemble](#-vue-densemble)
2. [🎯 Fonctionnalités Avancées](#-fonctionnalités-avancées)
3. [📦 Architecture Technique](#-architecture-technique)
4. [⚡ Installation Rapide](#-installation-rapide)
5. [🔧 Utilisation de Base](#-utilisation-de-base)
6. [🤖 Intégration IA & NLP](#-intégration-ia--nlp)
7. [💾 Stockage Multi-Backend](#-stockage-multi-backend)
8. [🔍 Système d'Indexation](#-système-dindexation)
9. [🔧 API Python](#-api-python)
10. [📊 Commandes Référence](#-commandes-référence)
11. [🧪 Tests & Validation](#-tests--validation)
12. [🚀 Déploiement](#-déploiement)
13. [🤝 Contribution](#-contribution)
14. [📄 Licence](#-licence)

---

## 🚀 Vue d'Ensemble

**GSQL** est un système de gestion de base de données relationnelle écrit entièrement en Python. Il combine la simplicité de SQLite avec des fonctionnalités avancées d'intelligence artificielle, de traitement du langage naturel (NLP) et de stockage multi-backend.

> **Notre philosophie :** La puissance du SQL, la simplicité de Python, l'intelligence de l'IA.

### Caractéristiques principales

*   🔹 **Moteur SQL complet** avec support des transactions ACID.
*   🔹 **Shell interactif** avec auto-complétion et coloration syntaxique.
*   🔹 **Traduction naturelle** de langage vers SQL (NLP).
*   🔹 **Stockage flexible** (SQLite, YAML, Mémoire).
*   🔹 **Système d'indexation avancé** (B+Tree).
*   🔹 **Extensibilité** via fonctions Python personnalisées.

| Information | Détail |
| :--- | :--- |
| **Version** | `3.0.0` |
| **Statut** | Production Ready |
| **Base de Données** | SQLite avec extensions GSQL |
| **Langage** | Python 3.8+ |

---

## 🎯 Fonctionnalités Avancées

### ✅ Fonctionnalités Principales
*   **Moteur SQL complet** : Support `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `CREATE TABLE`.
*   **Transactions ACID** : Avec isolation des niveaux pour garantir l'intégrité des données.
*   **Cache intelligent** : Optimisation des requêtes et mise en cache des résultats.
*   **Shell interactif** : Historique des commandes et auto-complétion intuitive.
*   **Gestion des erreurs** : Messages détaillés avec suggestions de correction automatique.
*   **Support multi-backend** : SQLite, YAML, Mémoire.

### 🔧 Extensions GSQL
*   **Fonctions Python** : Exécutez du code Python directement dans vos requêtes SQL.
*   **Indexation B+Tree** : Performances optimisées pour les grands volumes de données.
*   **NLP intégré** : Traduction automatique du langage naturel vers SQL.
*   **Migration automatique** : Outils pour migrer entre différents backends.
*   **Journalisation** : Logs avancés avec niveaux configurables.

### 🧠 Intelligence Intégrée
*   **Traducteur NLP** : *"Montre-moi les 10 meilleurs clients"* → Devient une requête SQL valide.
*   **Détection d'intention** : Comprend le but de la requête utilisateur.
*   **Suggestions** : Basées sur le schéma de la base de données.
*   **Optimisation** : Réécriture automatique des requêtes complexes.

---

## 📦 Architecture Technique

La structure du projet est modulaire et maintenable :

```text
gsql/
├── 📁 core/
│   ├── database.py           # Classe Database principale
│   ├── executor.py           # Exécuteur de requêtes
│   ├── parser.py             # Parseur SQL avancé
│   └── index.py              # Gestionnaire d'index
│
├── 📁 storage/               # Moteurs de stockage
│   ├── storage.py            # Interface de stockage
│   ├── sqlite_storage.py     # Backend SQLite
│   ├── yaml_storage.py       # Backend YAML
│   ├── buffer_pool.py        # Cache de pages
│   └── exceptions.py         # Exceptions spécifiques
│
├── 📁 index/                 # Système d'indexation
│   ├── btree.py              # Implémentation B+Tree
│   └── base_index.py         # Interface d'index
│
├── 📁 nlp/                   # Traitement langage naturel
│   ├── translator.py         # Traducteur NL → SQL
│   └── intent_detector.py    # Détection d'intention
│
├── 📁 functions/             # Fonctions SQL étendues
│   ├── user_functions.py     # Fonctions utilisateur
│   └── builtin_functions.py  # Fonctions intégrées
│
├── 📁 cli/                   # Interface ligne de commande
│   ├── shell.py              # Shell interactif
│   └── commands.py           # Commandes système
│
├── 📁 utils/                 # Utilitaires
│   └── logger.py             # Système de journalisation
│
├── 📁 exceptions/            # Gestion des erreurs
│   └── exceptions.py         # Exceptions personnalisées
│
├── __init__.py               # Initialisation du module
├── __main__.py               # Point d'entrée principal
└── requirements.txt          # Dépendances
```

### Composants Clés

#### 1. Core Database (`database.py`)
Le chef d'orchestre du système.

```python
class Database:
    """Point d'entrée principal du système GSQL"""
    
    def __init__(self, storage_backend='sqlite', config=None):
        self.storage = self._init_storage(storage_backend, config)
        self.executor = QueryExecutor(self.storage)
        self.parser = SQLParser()
        self.index_manager = IndexManager()
        self.cache = QueryCache()
        self.logger = GLogger()
    
    def execute(self, query: str, params=None, many=False):
        """Exécute une requête SQL"""
        # 1. Parsing
        parsed = self.parser.parse(query)
        
        # 2. Vérification du cache
        if cached := self.cache.get(query, params):
            return cached
        
        # 3. Exécution
        result = self.executor.execute(parsed, params, many)
        
        # 4. Mise en cache
        self.cache.set(query, params, result)
        
        return result
```

#### 2. SQL Parser (`parser.py`)
*   Parseur SQL récursif descendant.
*   Support des clauses complexes (JOIN, GROUP BY, HAVING).
*   Validation syntaxique et sémantique.
*   Génération d'AST (Abstract Syntax Tree).

#### 3. Query Executor (`executor.py`)

```python
class QueryExecutor:
    """Exécuteur de requêtes optimisé"""
    
    def execute(self, parsed_query, params=None, many=False):
        query_type = parsed_query['type']
        
        if query_type == 'select':
            return self._execute_select(parsed_query, params)
        elif query_type == 'insert':
            return self._execute_insert(parsed_query, params, many)
        elif query_type == 'update':
            return self._execute_update(parsed_query, params)
        elif query_type == 'delete':
            return self._execute_delete(parsed_query, params)
        elif query_type == 'create_table':
            return self._execute_create_table(parsed_query)
```

#### 4. Storage System (`storage/`)
*   **Interface unifiée** : Abstraction commune pour tous les backends.
*   **SQLiteStorage** : Backend SQLite haute performance.
*   **YAMLStorage** : Stockage lisible pour développement et tests.
*   **BufferPool** : Cache LRU pour les pages de données.

#### 5. Index System (`index.py`, `btree.py`)

```python
class BTree:
    """Implémentation B+Tree pour indexation rapide"""
    
    def __init__(self, order=100):
        self.order = order
        self.root = BTreeNode(is_leaf=True)
    
    def insert(self, key, value):
        """Insertion optimisée avec rééquilibrage automatique"""
        if self.root.is_full():
            new_root = BTreeNode()
            new_root.children.append(self.root)
            self._split_child(new_root, 0)
            self.root = new_root
        self._insert_non_full(self.root, key, value)
```

#### 6. NLP Translator (`nlp/translator.py`)

```python
class NLTranslator:
    """Traducteur de langage naturel vers SQL"""
    
    def translate(self, natural_language: str) -> str:
        """
        Traduit une phrase en langage naturel en requête SQL
        
        Exemple:
        "Montre-moi les 10 meilleurs clients" →
        "SELECT * FROM clients ORDER BY score DESC LIMIT 10"
        """
        intent = self.detector.detect_intent(natural_language)
        entities = self.extractor.extract_entities(natural_language)
        sql = self.generator.generate_sql(intent, entities)
        return sql
```

---

## ⚡ Installation Rapide

### Méthode 1: Installation via pip

```bash
# Clonez le dépôt
git clone https://github.com/gopu-inc/gsql.git
cd gsql

# Installation des dépendances
pip install -r requirements.txt

# Installation en mode développement
pip install -e .

# Vérification
gsql --version
```

### Méthode 2: Installation directe

```bash
# Installation depuis GitHub
pip install git+https://github.com/gopu-inc/gsql.git

# Ou avec spécification de version
pip install git+https://github.com/gopu-inc/gsql.git@main
```

### Méthode 3: Docker

```bash
# Construction de l'image
docker build -t gsql .

# Exécution avec volume persistant
docker run -it -v $(pwd)/data:/data gsql

# Exécution avec configuration personnalisée
docker run -it -v $(pwd)/config:/config gsql --config /config/gsql.yaml
```

### Dépendances (`requirements.txt`)
*   `sqlite3>=3.35.0`
*   `PyYAML>=6.0`
*   `click>=8.0.0`
*   `colorama>=0.4.4`
*   `prompt-toolkit>=3.0.0`
*   `nltk>=3.6.0`
*   `pandas>=1.3.0`
*   `numpy>=1.21.0`

---

## 🔧 Utilisation de Base

### 1. Mode Shell Interactif

```bash
# Lancement du shell
gsql

# Ou avec fichier de base spécifique
gsql --database ma_base.db

# Mode verbose pour débogage
gsql --verbose
```

**Dans le shell GSQL :**

```sql
-- Création d'une table
CREATE TABLE clients (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    nom TEXT NOT NULL,
    email TEXT UNIQUE,
    solde DECIMAL(10, 2),
    actif BOOLEAN DEFAULT TRUE,
    inscription DATE DEFAULT CURRENT_DATE
);

-- Insertion de données
INSERT INTO clients (nom, email, solde) 
VALUES 
    ('Alice Dupont', 'alice@example.com', 1500.50),
    ('Bob Martin', 'bob@example.com', 2300.75);

-- Requête avec NLP (Commande magique NL>)
NL> Montre-moi les clients avec plus de 2000 euros
-- Résultat automatique :
-- SELECT * FROM clients WHERE solde > 2000;

-- Indexation
CREATE INDEX idx_solde ON clients(solde);

-- Vérification des performances
EXPLAIN SELECT * FROM clients WHERE solde > 2000;
```

### 2. Utilisation Programmatique

```python
from gsql import Database, GSQLException

# Connexion à une base
db = Database('sqlite', {'path': 'ma_base.db'})

# Exécution de requêtes
try:
    # Création de table
    db.execute("""
        CREATE TABLE produits (
            id INTEGER PRIMARY KEY,
            nom TEXT NOT NULL,
            prix DECIMAL(10, 2),
            stock INTEGER
        )
    """)
    
    # Insertion multiple
    produits = [
        ('Laptop', 999.99, 50),
        ('Smartphone', 699.99, 150),
        ('Tablette', 399.99, 75)
    ]
    
    db.execute(
        "INSERT INTO produits (nom, prix, stock) VALUES (?, ?, ?)",
        produits,
        many=True
    )
    
    # Requête avec jointure
    result = db.execute("""
        SELECT p.nom, p.prix, c.nom as categorie
        FROM produits p
        JOIN categories c ON p.categorie_id = c.id
        WHERE p.prix > 500
        ORDER BY p.prix DESC
        LIMIT 10
    """)
    
    print(f"Résultats: {result['rows']}")
    print(f"Colonnes: {result['columns']}")
    print(f"Temps d'exécution: {result['execution_time_ms']}ms")
    
except GSQLException as e:
    print(f"Erreur GSQL: {e}")
    print(f"Suggestion: {e.suggestion}")
```

### 3. Utilisation avec NLP (Python)

```python
from gsql.nlp.translator import NLTranslator

translator = NLTranslator()

queries = [
    "Combien de clients avons-nous ?",
    "Montre les 5 produits les plus chers",
    "Quels clients n'ont pas acheté depuis 30 jours ?",
    "Donne-moi le total des ventes par mois"
]

for nl_query in queries:
    sql = translator.translate(nl_query)
    print(f"NL: {nl_query}")
    print(f"SQL: {sql}\n")
```

---

## 🤖 Intégration IA & NLP

### Traducteur NLP Avancé

Le module `nlp/translator.py` offre des capacités avancées de compréhension du langage naturel.

```python
class NLTranslator:
    """Traducteur NL→SQL avec apprentissage contextuel"""
    
    def __init__(self):
        self.intent_detector = IntentDetector()
        self.entity_extractor = EntityExtractor()
        self.sql_generator = SQLGenerator()
        self.context_manager = ContextManager()
        
    def translate(self, text: str, context=None) -> Dict:
        """
        Traduit un texte en langage naturel en requête SQL
        """
        # 1. Analyse contextuelle
        context = self.context_manager.update_context(text, context)
        
        # 2. Détection d'intention
        intent = self.intent_detector.detect(text)
        
        # 3. Extraction d'entités
        entities = self.entity_extractor.extract(text, intent)
        
        # 4. Génération SQL
        sql, confidence = self.sql_generator.generate(intent, entities, context)
        
        # 5. Validation sémantique
        if confidence > 0.7:
            sql = self._validate_sql(sql)
        
        return {
            'sql': sql,
            'confidence': confidence,
            'entities': entities,
            'intent': intent,
            'explanation': self._generate_explanation(intent, entities)
        }
```

### Exemples de Traduction

| Langage Naturel | SQL Généré | Confiance |
| :--- | :--- | :--- |
| "Affiche les 10 premiers clients" | `SELECT * FROM clients LIMIT 10` | 95% |
| "Combien de commandes en attente ?" | `SELECT COUNT(*) FROM commandes WHERE statut = 'en_attente'` | 88% |
| "Revenu total du mois dernier" | `SELECT SUM(montant) FROM ventes WHERE date >= date('now', '-1 month')` | 92% |
| "Clients sans achat depuis 30 jours" | `SELECT * FROM clients WHERE dernier_achat < date('now', '-30 days')` | 85% |

### Configuration NLP (`config/nlp_config.yaml`)

```yaml
nlp:
  models:
    intent: "fr_core_news_sm"
    entity: "custom_entity_model"
  vocabulary:
    tables:
      - clients
      - produits
    synonyms:
      "montre": ["affiche", "liste", "donne"]
      "combien": ["nombre", "quantité", "total"]
  min_confidence: 0.6
  max_suggestions: 3
  language: "fr"
```

---

## 💾 Stockage Multi-Backend

### 1. SQLite Storage (`storage/sqlite_storage.py`)
Backend haute performance utilisant SQLite avec des optimisations spécifiques (WAL, Cache, etc.).

```python
class SQLiteStorage(StorageBackend):
    """Backend SQLite avec optimisations GSQL"""
    # ... (implémentation optimisée avec BufferPool)
```

### 2. YAML Storage (`storage/yaml_storage.py`)
Backend léger, idéal pour le développement et les tests unitaires.

```python
class YAMLStorage(StorageBackend):
    """Stockage YAML pour tests et prototypes"""
    # ... (chargement et sauvegarde en format lisible)
```

### 3. Migration entre Backends

```python
from gsql import Database, MigrationTool

# Migration de YAML vers SQLite
source = Database('yaml', {'path': 'data.yaml'})
target = Database('sqlite', {'path': 'production.db'})

migrator = MigrationTool(source, target)
migrator.migrate_all()
```

---

## 🔍 Système d'Indexation

### B+Tree Implementation (`btree.py`)
GSQL implémente son propre arbre B+ pour une indexation ultra-rapide indépendante du backend de stockage sous-jacent.

```python
class BTree:
    """Implémentation B+Tree optimisée pour les bases de données"""
    
    def __init__(self, order=100, unique=False):
        self.order = order  # Ordre de l'arbre
        self.unique = unique
        self.root = BTreeNode(is_leaf=True)
        # ...
```

### Utilisation des Index

```python
from gsql import Database

db = Database()
# Création d'index
db.create_index(
    name='idx_titre',
    table='documents',
    columns=['titre'],
    index_type='btree',
    unique=True
)

# Vérification de l'utilisation des index
explanation = db.explain("""
    SELECT * FROM documents 
    WHERE titre LIKE 'Introduction%'
""")
print(f"Index utilisés: {explanation['indexes_used']}")
```

---

## 🔧 API Python

### Client Complet (`GSQLClient`)

Voici un exemple d'implémentation d'un client riche incluant l'export vers Pandas et des backups.

```python
from gsql import Database, GSQLException, connect
from gsql.functions import register_function
import pandas as pd

class GSQLClient:
    """Client GSQL complet avec fonctionnalités avancées"""
    
    def __init__(self, connection_string=None, **kwargs):
        self.db = connect(connection_string, **kwargs)
        self._setup_custom_functions()
    
    def _setup_custom_functions(self):
        # Enregistrement de fonctions custom (ex: formatage, calculs taxes)
        register_function(self.db, 'format_currency', lambda amount: f"${amount:,.2f}" if amount else None)
    
    def query_to_dataframe(self, query: str, params=None) -> pd.DataFrame:
        """Exécute une requête et retourne un DataFrame pandas"""
        result = self.db.execute(query, params)
        if not result['rows']:
            return pd.DataFrame()
        return pd.DataFrame(result['rows'], columns=result['columns'])
    
    def backup(self, backup_path: str):
        """Sauvegarde complète de la base"""
        # ... (Logique de sauvegarde atomique)
```

---

## 📊 Commandes Référence

### Commandes SQL Supportées

```sql
-- CRÉATION
CREATE TABLE table (id INTEGER, col TYPE);
CREATE INDEX idx ON table(col);

-- MANIPULATION
INSERT INTO table VALUES (v1, v2);
SELECT * FROM table WHERE cond;
UPDATE table SET col=val WHERE cond;
DELETE FROM table WHERE cond;

-- AVANCÉ
SELECT * FROM t1 JOIN t2 ON t1.id = t2.id;
SELECT col FROM t WHERE col IN (SELECT col FROM t2);
```

### Commandes Spécifiques GSQL

*   `NL> [phrase]` : Traduction et exécution de langage naturel.
*   `EXPLAIN SELECT ...` : Affiche le plan d'exécution.
*   `SHOW STATS` : Affiche les métriques de performance.
*   `CACHE STATS` : Statistiques du cache.
*   `BACKUP TO 'path'` : Effectue une sauvegarde à chaud.

### Commandes CLI

```bash
gsql --database DB_PATH      # Connexion
gsql --file script.sql       # Exécution de script
gsql --export csv            # Export de données
gsql --migrate               # Outil de migration
```

---

## 🧪 Tests & Validation

La suite de tests est structurée pour couvrir les unités, l'intégration, les fonctionnalités et les performances.

### Structure

*   `tests/unit/`: Tests unitaires des composants (Parser, Executor).
*   `tests/integration/`: Tests entre modules (Backend, Migration).
*   `tests/functional/`: Tests bout en bout (CLI).
*   `tests/benchmarks/`: Tests de charge et performance.

### Exemple de Test Unitaire

```python
import unittest
from gsql import Database

class TestDatabase(unittest.TestCase):
    def test_nlp_translation(self):
        """Test traduction NLP"""
        self.db.execute("CREATE TABLE products (id INTEGER, name TEXT)")
        
        # Traduction NLP
        from gsql.nlp.translator import NLTranslator
        translator = NLTranslator()
        
        nl_query = "Montre les produits"
        translated = translator.translate(nl_query, context={'tables': ['products']})
        
        self.assertIn('SELECT', translated['sql'])
```

### Benchmarks de Performance

Le projet inclut des scripts (`benchmark_insert`, `benchmark_select_with_index`) pour valider les performances avant mise en production.

---

## 🚀 Déploiement

### 1. Configuration de Production (`config/production.yaml`)

```yaml
database:
  backend: sqlite
  path: /var/lib/gsql/production.db
  options:
    journal_mode: WAL
    cache_size: -10000

performance:
  buffer_pool_size: 5000
  max_connections: 50

monitoring:
  enabled: true
  metrics_port: 9090
  alerting:
    email: admin@example.com
```

### 2. Docker Compose

```yaml
version: '3.8'
services:
  gsql:
    build: .
    ports:
      - "8080:8080"  # API
      - "9090:9090"  # Metrics
    volumes:
      - gsql_data:/var/lib/gsql
    environment:
      - GSQL_CONFIG=/config/production.yaml
```

### 3. Kubernetes

Des manifestes complets (`Deployment`, `Service`, `ConfigMap`, `PVC`) sont fournis pour un déploiement sur cluster Kubernetes.

### 4. Scripts d'automatisation
Un script complet `deploy.sh` et un script de vérification de santé `health_check.py` sont inclus pour automatiser le cycle de vie de l'application.

---

## 🤝 Contribution

Nous accueillons avec plaisir les contributions !

### Guide de Contribution
1.  **Fork** le dépôt.
2.  **Clone** votre fork : `git clone https://github.com/votre-username/gsql.git`
3.  **Branche** : `git checkout -b feature/ma-fonctionnalité`
4.  **Code & Test** : `pytest tests/`
5.  **Commit** : `git commit -m "Ajout de ma fonctionnalité"`
6.  **Push** & **Pull Request**.

### Normes de Code
*   **PEP 8** : Respectez les conventions Python.
*   **Docstrings** : Format Google.
*   **Typing** : Type hints Python 3.8+ requis.

---

## 📄 Licence

```text
MIT License

Copyright (c) 2024 Gopu Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files...
```

### 📞 Support & Contact

*   **Documentation** : [https://gsql.readthedocs.io](https://gsql.readthedocs.io)
*   **Issues** : [GitHub Issues](https://github.com/gopu-inc/gsql/issues)
*   **Email** : support@gopu-inc.com

---

### 🌟 Étoilez-nous !

Si GSQL vous est utile, n'hésitez pas à donner une étoile ⭐ sur GitHub !

```bash
git clone https://github.com/gopu-inc/gsql.git
```

**GSQL - La puissance de SQL avec la simplicité de Python et l'intelligence de l'IA.** 🚀
```
