dgarzon/SQL-Explainer

1---2title: SQL Explainer Agent3colorFrom: blue4colorTo: green5sdk: docker6app_port: 78607---8 9# SQL Explainer Agent10 11Simple Python app that explains SQL queries for analytics or business users using a small open model running locally inside the Hugging Face Space.12 13This repo includes:14- A CLI version in `sql_explainer.py`15- A Streamlit version in `streamlit_app.py`16- Shared local inference logic in `sql_explainer_core.py`17- A `Dockerfile` ready for Hugging Face Spaces18 19## Fully free setup20 21This version does not use Hugging Face Inference Providers, API tokens, or paid endpoints.22 23It runs the model directly inside the Space on free `CPU Basic` hardware.24 25## Recommended model26 27Default model:28 29```text30Qwen/Qwen2.5-0.5B-Instruct31```32 33Why this default:34- Small enough to run on free CPU Spaces35- Better multilingual support than most tiny models36- Good instruction following for a narrow SQL-explainer task37- Public model on Hugging Face38 39Tradeoff:40- It is slower and less capable than hosted 7B+ models41- The first request can take a while because the Space must download and load the model42 43The UI only exposes small local models that are realistic on free CPU hardware:44- `Qwen/Qwen2.5-0.5B-Instruct`45- `HuggingFaceTB/SmolLM2-360M-Instruct`46- `Qwen/Qwen2.5-1.5B-Instruct`47 48Important:49- Do not use provider suffixes such as `:featherless-ai`50- Do not point the app to Inference Providers if the requirement is zero cost51 52## Requirements53 54- Python 3.9+55 56## Install locally57 58```bash59python3 -m pip install -r requirements.txt60```61 62## Run the Streamlit app locally63 64```bash65streamlit run streamlit_app.py66```67 68Then open the local URL shown by Streamlit, paste your SQL query, and click `Explain Query`.69 70## Run the CLI version71 72```bash73python3 sql_explainer.py74```75 76Paste the SQL query and finish with one of these options:77- A blank line after the SQL78- A line containing only `:end`79- `Ctrl-D` on macOS/Linux or `Ctrl-Z` then Enter on Windows80 81## Environment variables82 83```bash84export LOCAL_MODEL_ID=Qwen/Qwen2.5-0.5B-Instruct85export MAX_NEW_TOKENS=32086export MAX_SQL_CHARS=800087```88 89## Deploy to Hugging Face Spaces90 91This repo is prepared for a Docker Space because Hugging Face deprecated the native Streamlit SDK.92 93Steps:941. Create a new Space and choose `Docker`.952. Push this repository to the Space.963. Do not add any secret or token.974. Launch the Space.98 99The app listens on port `7860`, which matches the Space configuration in the README front matter and the `Dockerfile`.100 101## Notes102 103- Free `CPU Basic` hardware currently provides 2 vCPU, 16 GB RAM and 50 GB ephemeral disk.104- Because the model runs locally, the app stays fully free but responses are slower than hosted inference.105- SQL input is capped with `MAX_SQL_CHARS` to reduce abuse in a public demo.106