|
1 | | -# Deployment — Streamlit Community Cloud |
2 | | - |
3 | | -The fastest free path to a public demo. ~5 minutes after the repo |
4 | | -is on GitHub. |
5 | | - |
6 | | -## What's shipped in the repo |
7 | | - |
8 | | -The deployed version intentionally carries a subset of the BIRD |
9 | | -Mini-Dev databases, not all 11: |
10 | | - |
11 | | -| DB | size | source | shipped | |
12 | | -|---|---|---|---| |
13 | | -| `chinook` | 1 MB | Chinook sample | ✅ | |
14 | | -| `bird_california_schools` | 11 MB | BIRD Mini-Dev | ✅ | |
15 | | -| `bird_debit_card_specializing` | 34 MB | BIRD Mini-Dev | ✅ | |
16 | | -| `bird_financial` | 68 MB | BIRD Mini-Dev | ✅ | |
17 | | -| `bird_formula_1` | 22 MB | BIRD Mini-Dev | ✅ | |
18 | | -| `bird_student_club` | 2.6 MB | BIRD Mini-Dev | ✅ | |
19 | | -| `bird_superhero` | 0.2 MB | BIRD Mini-Dev | ✅ | |
20 | | -| `bird_thrombosis_prediction` | 7 MB | BIRD Mini-Dev | ✅ | |
21 | | -| `bird_toxicology` | 2.6 MB | BIRD Mini-Dev | ✅ | |
22 | | -| `bird_card_games` | 250 MB | BIRD Mini-Dev | ❌ — over GitHub 100 MB/file limit | |
23 | | -| `bird_codebase_community` | 460 MB | BIRD Mini-Dev | ❌ — over GitHub 100 MB/file limit | |
24 | | -| `bird_european_football_2` | 571 MB | BIRD Mini-Dev | ❌ — over GitHub 100 MB/file limit | |
25 | | - |
26 | | -The three excluded DBs are gitignored. The registry in |
27 | | -`src/nl_sql/db/registry.py` skips DBs whose SQLite file isn't on |
28 | | -disk, so the deployed UI's database selector only lists the 9 |
29 | | -shipped databases. |
30 | | - |
31 | | -`chroma_data/` is also committed (~58 MB) so the app doesn't have |
32 | | -to re-embed the schema chunks on first cold start. Orphan chunks |
33 | | -for the three excluded DBs are harmless — the registry never |
34 | | -asks for them. |
35 | | - |
36 | | -## Steps |
37 | | - |
38 | | -1. **Create a public GitHub repo.** Name suggestion: `NL_SQL` or |
39 | | - `nl-sql-portfolio`. Do not initialise with a README — we already |
40 | | - have one. |
41 | | - |
42 | | -2. **Push the local main branch:** |
43 | | - ```powershell |
44 | | - git remote add origin https://github.com/<your-username>/<repo>.git |
45 | | - git push -u origin main |
46 | | - ``` |
47 | | - Repo size will be ~150 MB. The push takes a minute or two. |
48 | | - |
49 | | -3. **Sign in to <https://share.streamlit.io>** with the same |
50 | | - GitHub account. |
51 | | - |
52 | | -4. **New app:** |
53 | | - - Repository: pick the repo you just pushed. |
54 | | - - Branch: `main`. |
55 | | - - Main file path: `app/streamlit_app.py`. |
56 | | - - App URL: defaults to |
57 | | - `https://<your-username>-<repo>-app-streamlit-app-<hash>.streamlit.app`. |
58 | | - You can rename via the dashboard later. |
59 | | - |
60 | | -5. **Set the secret:** |
61 | | - - In the Streamlit Cloud app dashboard → "Settings" → "Secrets". |
62 | | - - Add the API key in TOML format: |
63 | | - ```toml |
64 | | - MISTRAL_API_KEY = "your-key-here" |
65 | | - ``` |
66 | | - - Streamlit Cloud injects every key in this TOML as an |
67 | | - environment variable, which `pydantic-settings` picks up. |
68 | | - - Click "Save". The app reboots automatically. |
69 | | - |
70 | | -6. **First load.** |
71 | | - The cold start is ~30 seconds — Streamlit Cloud installs the |
72 | | - `ui` extra deps (streamlit, plotly, pandas), reads the prebuilt |
73 | | - Chroma index, and warms the LLM provider. Subsequent loads are |
74 | | - sub-second. |
| 1 | +# Deployment — Hugging Face Space (Docker) |
| 2 | + |
| 3 | +The public demo runs on a Hugging Face Space with a Docker runtime (free tier): |
| 4 | +<https://liovina-nl-sql.hf.space>. Cold start ~30 s, then interactive. |
| 5 | + |
| 6 | +## Deploy policy: only what git tracks, then prune |
| 7 | + |
| 8 | +The deploy publishes **exactly the files git tracks** (`git ls-files`), never the |
| 9 | +working tree. Working-kitchen files — internal notes, audits, `.env`, scratch |
| 10 | +reports — are gitignored and a repo-hygiene CI gate fails if any slip into the |
| 11 | +index, so they cannot reach the Space. The upload also **prunes** the Space: files |
| 12 | +removed from the repo are deleted on the host, not left behind from an earlier push. |
| 13 | + |
| 14 | +The deploy script itself (`.deploy_hf.py`) is repo-local (it reads a local token |
| 15 | +and Mistral key by path) and is intentionally not committed. It: |
| 16 | + |
| 17 | +1. computes the file set from `git ls-files` minus a publish-exclude list |
| 18 | + (`tests/`, `.github/`, `docs/research/`, `reviews/`, `eval/baselines/`); |
| 19 | +2. drops anything the hygiene detector flags; |
| 20 | +3. uploads via `huggingface_hub`, then prunes remote files no longer present; |
| 21 | +4. supports `--self-test` (a gate that runs before upload) and `--dry-run`. |
| 22 | + |
| 23 | +## What ships to the Space |
| 24 | + |
| 25 | +The Space is **SQLite-only** — `psycopg` is pruned from its `requirements.txt`, so |
| 26 | +the Postgres path (see README) is not present there; it is for local/CI use. The |
| 27 | +Space carries a subset of the BIRD Mini-Dev databases (the three largest exceed |
| 28 | +GitHub's 100 MB/file limit and are gitignored): |
| 29 | + |
| 30 | +| DB | size | shipped | |
| 31 | +|---|---|---| |
| 32 | +| `chinook` | 1 MB | ✅ | |
| 33 | +| `bird_california_schools` | 11 MB | ✅ | |
| 34 | +| `bird_debit_card_specializing` | 34 MB | ✅ | |
| 35 | +| `bird_financial` | 68 MB | ✅ | |
| 36 | +| `bird_formula_1` | 22 MB | ✅ | |
| 37 | +| `bird_student_club` | 2.6 MB | ✅ | |
| 38 | +| `bird_superhero` | 0.2 MB | ✅ | |
| 39 | +| `bird_thrombosis_prediction` | 7 MB | ✅ | |
| 40 | +| `bird_toxicology` | 2.6 MB | ✅ | |
| 41 | +| `bird_card_games` | 250 MB | ❌ over 100 MB/file | |
| 42 | +| `bird_codebase_community` | 460 MB | ❌ over 100 MB/file | |
| 43 | +| `bird_european_football_2` | 571 MB | ❌ over 100 MB/file | |
| 44 | + |
| 45 | +The registry in `src/nl_sql/db/registry.py` skips DBs whose SQLite file isn't on |
| 46 | +disk, so the deployed UI's selector lists only the 9 shipped databases. All 11 |
| 47 | +BIRD slices are present locally for eval. `chroma_data/` is committed (~58 MB) so |
| 48 | +the app doesn't re-embed schema chunks on cold start. |
| 49 | + |
| 50 | +## Secret |
| 51 | + |
| 52 | +The Space needs one secret — `MISTRAL_API_KEY` — set in the Space's Settings → |
| 53 | +Variables and secrets. `pydantic-settings` reads it from the environment. |
75 | 54 |
|
76 | 55 | ## Updating |
77 | 56 |
|
78 | | -Push to `main` → Streamlit Cloud auto-redeploys. No manual step. |
79 | | - |
80 | | -## Why not Vercel |
81 | | - |
82 | | -Streamlit is a long-running Tornado/WebSocket server with stateful |
83 | | -per-session memory. Vercel's serverless model gives you ~10-second |
84 | | -function executions with no persistent process — every page-reload |
85 | | -would lose `st.session_state` and every user keystroke would race |
86 | | -against a cold start. The hacks that "work" run Streamlit in a |
87 | | -container behind Vercel's edge layer, which trades all of Vercel's |
88 | | -strengths for none of Streamlit's. Streamlit Community Cloud is |
89 | | -the natively-supported home for this app. |
| 57 | +Re-run the local deploy script; it re-uploads the tracked set and prunes. CI (tests |
| 58 | ++ repo-hygiene) gates `main` before any deploy is worth doing. |
0 commit comments