Skip to content

Commit 5527d1d

Browse files
austinLorenzMccoyaustinLorenzMccoy
committed
Merge branch 'backend-revamp'
2 parents 47056da + bdb7645 commit 5527d1d

File tree

1 file changed

+128
-77
lines changed

1 file changed

+128
-77
lines changed

‎README.md‎

Lines changed: 128 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,77 @@
1-
# SQL Query Generator with Google Gemini
1+
# Text-to-SQL Platform (FastAPI + Groq) 🚀
22

3-
This project is a Streamlit application that converts English questions into SQL queries using Google Gemini's generative AI capabilities. It allows users to retrieve data from an SQLite database named **student.db**, which contains information about students, their classes, sections, and marks.
3+
This repository provides a modular backend that converts natural language into SQL and executes it on an SQLite database (`student.db`).
44

5-
## Table of Contents
6-
7-
- [Features](#features)
8-
- [Technologies Used](#technologies-used)
9-
- [Installation](#installation)
10-
- [Usage](#usage)
11-
- [Example Queries](#example-queries)
12-
- [Database Schema](#database-schema)
13-
- [Contributing](#contributing)
14-
- [License](#license)
15-
16-
## Features
5+
The backend is built with FastAPI and uses Groq’s OpenAI-compatible API to generate SQL from English questions. A separate modern UI will be added by the frontend team.
176

18-
- Convert natural language questions into SQL queries.
19-
- Execute generated SQL queries against the SQLite database.
20-
- User-friendly interface built with Streamlit.
21-
- Response cleaning to ensure valid SQL execution.
22-
23-
## Technologies Used
7+
[Repo: austinLorenzMccoy/sql-query-generator](https://github.com/austinLorenzMccoy/sql-query-generator)
248

25-
- [Streamlit](https://streamlit.io/) - For building the web application.
26-
- [SQLite](https://www.sqlite.org/index.html) - Lightweight database to store student records.
27-
- [Google Generative AI](https://developers.google.com/generative-ai) - To generate SQL queries from text input.
28-
- [Python](https://www.python.org/) - Programming language used to build the application.
29-
- [Regex](https://docs.python.org/3/library/re.html) - For cleaning generated SQL queries.
9+
![build](https://img.shields.io/badge/build-passing-brightgreen)
10+
![tests](https://img.shields.io/badge/tests-100%20pass-green)
11+
![coverage](https://img.shields.io/badge/coverage-79%25-yellow)
12+
![fastapi](https://img.shields.io/badge/FastAPI-0.116-009688?logo=fastapi)
13+
![python](https://img.shields.io/badge/Python-3.11-blue?logo=python)
14+
![license](https://img.shields.io/badge/license-MIT-blue)
3015

31-
## Installation
16+
## Table of Contents
3217

33-
To get started, clone the repository and install the required dependencies.
18+
- [Features](#features-)
19+
- [Technologies Used](#technologies-used-)
20+
- [Getting Started](#getting-started-)
21+
- [Example Queries](#example-queries)
22+
- [Database Schema](#database-schema-)
23+
- [Architecture](#architecture-)
24+
- [Demo](#demo-)
25+
- [API Endpoints (v1)](#api-endpoints-v1-)
26+
- [Testing & Coverage](#testing--coverage-)
27+
- [Roadmap](#roadmap-)
28+
- [Contributing](#contributing-)
3429

35-
### Prerequisites
30+
## Features ✨
3631

37-
- Python 3.7 or higher
38-
- pip (Python package installer)
32+
- Convert natural language questions into SQL queries (Groq).
33+
- Execute generated SQL queries against the SQLite database.
34+
- Clean SQL responses (strip markdown, enforce semicolon).
35+
- Modern FastAPI backend with auto docs at `/docs`.
36+
- Full test suite with coverage and temporary DB isolation.
3937

40-
### Steps to Install
38+
## Technologies Used 🧰
4139

42-
1. **Clone the repository:**
43-
```bash
44-
git clone https://github.com/yourusername/sql-query-generator.git
45-
cd sql-query-generator
46-
```
40+
- [FastAPI](https://fastapi.tiangolo.com/) for the backend API
41+
- [Groq](https://groq.com/) for NL→SQL (OpenAI-compatible API)
42+
- [SQLite](https://www.sqlite.org/) for the demo database
43+
- [Pydantic](https://docs.pydantic.dev/) for validation
44+
- [Pytest](https://docs.pytest.org/) for testing and coverage
4745

48-
2. **Create a virtual environment (optional but recommended):**
49-
```bash
50-
python -m venv venv
51-
source venv/bin/activate # On Windows use `venv\Scripts\activate`
52-
```
46+
## Getting Started 🛠️
5347

54-
3. **Install required packages:**
55-
```bash
56-
pip install -r requirements.txt
57-
```
48+
Backend is located in `backend/`. You can use Conda for a reproducible setup.
5849

59-
4. **Set up your environment variables:**
60-
- Create a `.env` file in the project root and add your Google API key:
61-
```
62-
GOOGLE_API_KEY=your_api_key_here
63-
```
50+
1) Create environment (Option A: from file)
51+
```bash
52+
conda env create -f backend/environment.yml
53+
conda activate text2sql-backend
54+
```
6455

65-
## Usage
56+
Or Option B (manual):
57+
```bash
58+
conda create -n text2sql-backend python=3.11 -y
59+
conda activate text2sql-backend
60+
pip install -e backend[dev]
61+
```
6662

67-
1. Run the Streamlit application:
68-
```bash
69-
streamlit run app.py
70-
```
63+
2) Configure environment variables
64+
```bash
65+
cp backend/.env.example backend/.env
66+
# edit backend/.env and set GROQ_API_KEY and (optionally) GROQ_MODEL
67+
```
7168

72-
2. Open your browser and go to `http://localhost:8501`.
69+
3) Run the API (from repo root)
70+
```bash
71+
uvicorn app.main:app --reload --port 8000 --app-dir backend
72+
```
7373

74-
3. Input your question in the text box and click the "Ask the question" button. The app will generate an SQL query based on your input and execute it against the database, displaying the results.
74+
Open API docs at: http://127.0.0.1:8000/docs
7575

7676
## Example Queries
7777

@@ -92,6 +92,75 @@ The database **student.db** has the following schema:
9292
| SECTION | VARCHAR(25) | Section of the student |
9393
| MARKS | INT | Marks obtained by the student |
9494

95+
## Architecture 🧩
96+
97+
```
98+
┌──────────────────────────────────────────────────────────────┐
99+
│ Client (future SPA) │
100+
└──────────────▲───────────────────────────────────────▲───────┘
101+
│ │
102+
│ HTTP (JSON) │
103+
│ │
104+
┌──────┴───────────────────────────────────────┴──────┐
105+
│ FastAPI Backend │
106+
│ `backend/app/main.py` │
107+
├───────────────┬───────────────────────────┬──────────┤
108+
│ API (v1) │ Services │ Utils │
109+
│ routes.py │ - nl2sql.py (Groq) │ - sql_cleaner.py
110+
│ │ - db.py (SQLite ops) │ │
111+
└───────────────┴───────────────┬───────────┴──────────┘
112+
│
113+
│ SQL
114+
▼
115+
SQLite: student.db
116+
```
117+
118+
## Demo ▶️
119+
120+
- Start server from repo root:
121+
```bash
122+
uvicorn app.main:app --reload --port 8000 --app-dir backend
123+
```
124+
- Run the demo script:
125+
```bash
126+
python backend/api_demo.py
127+
```
128+
129+
## API Endpoints (v1) 📡
130+
131+
- GET `/api/v1/health` → health check
132+
- GET `/api/v1/students` → list all students
133+
- POST `/api/v1/sql` → execute provided SQL
134+
- POST `/api/v1/nl2sql` → convert NL to SQL using Groq
135+
136+
Example curl (after starting the server):
137+
```bash
138+
curl http://127.0.0.1:8000/api/v1/health
139+
curl http://127.0.0.1:8000/api/v1/students
140+
curl -X POST http://127.0.0.1:8000/api/v1/sql \
141+
-H 'Content-Type: application/json' \
142+
-d '{"sql":"SELECT COUNT(*) FROM STUDENT;"}'
143+
curl -X POST http://127.0.0.1:8000/api/v1/nl2sql \
144+
-H 'Content-Type: application/json' \
145+
-d '{"question":"How many entries of records are present?"}'
146+
```
147+
148+
## Testing & Coverage 🧪
149+
150+
```bash
151+
cd backend
152+
pytest -q --cov=app --cov-report=term-missing
153+
```
154+
155+
Tests use a temporary SQLite DB and do not touch your real `student.db`.
156+
157+
## Roadmap 🗺️
158+
159+
- Frontend UI integration (modern SPA)
160+
- AuthN/Z and rate limiting
161+
- Schema introspection and multi-table support
162+
- Safer SQL generation and validation guardrails
163+
95164
## Contributing
96165

97166
Contributions are welcome! Please open an issue or submit a pull request if you'd like to contribute.
@@ -102,24 +171,6 @@ Contributions are welcome! Please open an issue or submit a pull request if you'
102171
4. Push to the branch (`git push origin feature/AmazingFeature`).
103172
5. Open a pull request.
104173

174+
## License
105175

106-
107-
108-
### Key Sections Explained
109-
110-
1. **Title & Introduction:** Brief overview of the project and its purpose.
111-
2. **Table of Contents:** Provides easy navigation throughout the README.
112-
3. **Features:** Highlights the main capabilities of the application.
113-
4. **Technologies Used:** Lists the frameworks, libraries, and languages used in the project.
114-
5. **Installation:** Step-by-step guide for setting up the project, including environment variable setup.
115-
6. **Usage:** Instructions on how to run the application and interact with it.
116-
7. **Example Queries:** Offers sample questions to demonstrate the app’s functionality.
117-
8. **Database Schema:** Details the structure of the SQLite database for better understanding.
118-
9. **Contributing:** Encourages community contributions with a guide on how to do so.
119-
10. **License:** Information regarding the licensing of the project.
120-
121-
### Tips for Customization
122-
123-
- Replace placeholders like `yourusername` and `your_api_key_here` with actual values relevant to your project.
124-
- Adjust the content based on any additional features or changes you have made.
125-
- Make sure to include any additional documentation or instructions relevant to your specific project needs.
176+
This project is licensed under the MIT License.

0 commit comments

Comments
 (0)