NL2SQL AI Agent

A C++ application that converts natural language questions into SQL queries using a fine-tuned T5 model. The application can work with both local T5 models and external API services.

Features

• Natural Language to SQL: Convert questions like "How many employees work in France?" into SQL queries
• Multiple Model Support: Works with local T5 models, T5 server, or external APIs (Gemini)
• Interactive CLI: User-friendly command-line interface with database selection
• MySQL Integration: Uses MySQL Connector/C++ X DevAPI for database operations
• Secure Configuration: Environment-based configuration for sensitive data

Prerequisites

System Requirements

• Windows 10/11 (tested on Windows)
• Visual Studio 2019/2022 with C++ development tools
• CMake 3.20+
• Python 3.8+ (for T5 model server)
• MySQL Server with X Plugin enabled (port 33060)

Dependencies

• vcpkg package manager
• MySQL Connector/C++ (X DevAPI)
• libcurl for HTTP requests
• nlohmann-json for JSON processing
• OpenSSL for secure connections

Installation & Setup

1. Install vcpkg and Dependencies

# Clone vcpkg if you don't have it
git clone https://github.com/Microsoft/vcpkg.git C:\vcpkg
cd C:\vcpkg
.\bootstrap-vcpkg.bat

# Install required packages
.\vcpkg install curl:x64-windows
.\vcpkg install nlohmann-json:x64-windows
.\vcpkg install openssl:x64-windows
.\vcpkg install mysql-connector-cpp:x64-windows

2. Set Environment Variables

# Set vcpkg toolchain
$env:VCPKG_ROOT = "C:\vcpkg"

# Set database password (REQUIRED)
$env:DB_PASS = "your_mysql_password"

# Optional: Set T5 server URL (if using local T5 model)
$env:T5_SERVER_URL = "http://127.0.0.1:5000"

# Optional: Set model path (if using local model directly)
$env:MODEL_PATH = "C:\path\to\your\model"

3. Build the Application

# Navigate to project directory
cd C:\path\to\NL2SQL-AI-Agent-

# Create build directory
mkdir build
cd build

# Configure with CMake
cmake .. -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake -DCMAKE_BUILD_TYPE=Release

# Build the application
cmake --build . --config Release

4. Setup T5 Model Server (Optional)

If you want to use the local T5 model:

# Install Python dependencies
pip install flask transformers torch

# Start the T5 server (run in separate terminal)
python t5_server.py C:\path\to\your\t5_model

# The server will run on http://127.0.0.1:5000

Usage

Basic Usage

# Set required environment variables
$env:DB_PASS = "your_mysql_password"

# Run the application
.\build\Release\nl2sql_agent.exe

Configuration Options

The application supports three modes:

1. T5 Server Mode (Recommended for local models):

   $env:T5_SERVER_URL = "http://127.0.0.1:5000"
   $env:DB_PASS = "your_password"

2. Local Model Mode:

   $env:MODEL_PATH = "C:\path\to\your\model"
   $env:DB_PASS = "your_password"

3. API Mode (Gemini):

   $env:GEMINI_API_KEY = "your_api_key"
   $env:DB_PASS = "your_password"

Interactive Usage

1. Start the application: Run nl2sql_agent.exe
2. Select database: Choose from available databases
3. Ask questions: Type natural language questions
4. View results: See generated SQL and query results
5. Exit: Type quit to exit

Example Questions

• "How many employees work in France?"
• "Show me all products with price greater than 100"
• "What is the average salary by department?"
• "List all customers from New York"

Project Structure

NL2SQL-AI-Agent-/
├── src/                    # C++ source files
│   ├── main.cpp           # Main application entry point
│   ├── NL2SQLAgent.cpp    # Core agent logic
│   ├── DatabaseManager.cpp # Database operations
│   ├── LocalModelClient.cpp # Local model integration
│   ├── T5ServerClient.cpp  # T5 server client
│   └── ...
├── include/               # Header files
├── t5_sql_model_final_v3/ # T5 model files
├── t5_server.py          # Python T5 server
├── CMakeLists.txt        # Build configuration
├── setup_t5.bat         # T5 setup script
└── README.md            # This file

Troubleshooting

Common Issues

1. "MySQL::mysqlx target not found"

   • Ensure MySQL Connector/C++ is installed via vcpkg
   • Check that vcpkg toolchain is properly set

2. "Environment variable DB_PASS not set"

   • Set the database password: $env:DB_PASS = "your_password"

3. "Connection failed"

   • Verify MySQL server is running
   • Check that X Plugin is enabled (port 33060)
   • Verify database credentials

4. "T5 server not responding"

   • Ensure T5 server is running: python t5_server.py model_path
   • Check server URL: $env:T5_SERVER_URL = "http://127.0.0.1:5000"

Build Issues

1. CMake configuration fails:

   • Ensure vcpkg is properly installed
   • Set VCPKG_ROOT environment variable
   • Use the correct toolchain file

2. Missing dependencies:

   • Install all required packages via vcpkg
   • Ensure packages are installed for the correct architecture (x64-windows)

Development

Adding New Features

1. New Model Support: Add client classes in src/ and include/
2. Database Support: Extend DatabaseManager.cpp
3. UI Improvements: Modify main.cpp for better user experience

Testing

# Test database connection
$env:DB_PASS = "test_password"
.\build\Release\nl2sql_agent.exe

# Test T5 server
python t5_server.py test_model
curl -X POST http://127.0.0.1:5000/health

License

This project is provided as-is for educational and research purposes.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Support

For issues and questions:

1. Check the troubleshooting section
2. Verify all dependencies are installed
3. Ensure environment variables are set correctly
4. Check MySQL server configuration