Natural Language to SQL Interface

A tool that allows users to query a PostgreSQL database on a remote server using plain English. The project uses a local LLM (Phi-3-mini) to translate natural language into SQL, then executes those queries on a Rutgers Ilab machine via SSH.

Project Features

• Natural Language Processing: Uses the Phi-3-mini-4k-instruct-q4 model to interpret user questions.
• Streamlit Frontend: A modern, interactive web interface for entering queries and viewing results.
• Interactive Data Tables: Database results are displayed in sortable, searchable tables with CSV download capability.
• Multi-Stage Output: The UI clearly separates the original user query, the generated SQL code, and the raw LLM status.
• Secure Remote Execution: Queries are sent to the Rutgers Ilab PostgreSQL server over an encrypted SSH connection.

Prerequisites

• Python 3.x
• A Rutgers CS account with access to the Ilab machines.
• The Phi-3-mini-4k-instruct-q4.gguf model file placed in the ./models/ directory.

Installation and Setup

1. Environment Setup

Create a virtual environment and install the required Python packages:

Bash
python3 -m venv venv
source venv/bin/activate
pip install llama-cpp-python streamlit pandas

2. Database Schema

The project relies on the HMDA dataset schema. To ensure the LLM fits within its context window, a simplified version of the schema is provided in schema_subset.sql. Ensure your PostgreSQL tables on the Ilab server match the names defined in this file.

3. Running the Application

First, start the Streamlit server on your local machine:

Bash
streamlit run app.py

Because the Ilab server is on a remote network, you must establish an SSH tunnel in a separate terminal to view the interface:

Bash
ssh -L 8501:localhost:8501 <Your_NetID>@ilab1.cs.rutgers.edu

Once the tunnel is active, open your browser to http://localhost:8501.

How to Use

1. Login: Enter your Ilab password in the sidebar. This is required for the script to establish an SSH connection.
2. Ask a Question: Type a natural language question in the text box (e.g., "Show me the top 10 rows of the agency table").
3. Review SQL: The app will display the SQL generated by the Phi-3 model.
4. Inspect Results: The data returned from the Ilab database will appear in an interactive table at the bottom of the page.

Project Structure

• app.py: The Streamlit frontend script.
• database_llm.py: Logic for initializing the LLM and handling the SSH connection to Ilab.
• ilab_script.py: The script that runs on the remote Ilab machine to interface with the PostgreSQL database.
• schema_subset.sql: A condensed version of the database schema used as context for the LLM.

Demo