README.md

---
title: NL to SQL Chatbot Demo
emoji: 🧠
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.29.0
app_file: app.py
pinned: false
---

# NL → SQL Chatbot Demo

This Hugging Face Space demonstrates a **simple natural-language-to-SQL chatbot** built in Python with **Gradio** and **SQLite**.

## What it does

- Creates a small demo database automatically on first startup
- Accepts business questions in plain English
- Converts the question into a SQL query using a lightweight rule-based parser
- Executes the SQL against the SQLite database
- Returns both the generated SQL and the result preview

## Demo schema

- `customers(id, name, country, segment)`
- `products(id, name, category, price)`
- `orders(id, customer_id, order_date, status, shipping_days)`
- `order_items(id, order_id, product_id, quantity, unit_price)`

## Example questions

- Show all customers
- Show orders from March 2026
- What is the total revenue by country?
- Top 5 products by revenue
- Average order value by customer
- How many orders are delayed?
- Show revenue by month
- List products in the Electronics category

## Local run

```bash
pip install -r requirements.txt
python app.py
```

## Files

- `app.py` — Gradio UI and query execution
- `init_db.py` — creates and seeds the example SQLite database
- `nl_to_sql.py` — converts natural language into SQL
- `demo_store.db` — created automatically at runtime

## Next steps

A natural upgrade path is to replace the rule-based `parse_question_to_sql()` function with an LLM prompt that:

1. Receives the schema
2. Generates SQL only
3. Applies guardrails (read-only, table allowlist)
4. Validates the result before execution

That lets you keep the same UI while making the translator more flexible.