Skip to content

Commit 9b08dca

Browse files
committed
docs: add clone-first quick start
1 parent 02d8ed6 commit 9b08dca

2 files changed

Lines changed: 81 additions & 7 deletions

File tree

‎README.md‎

Lines changed: 31 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -58,22 +58,46 @@ https://github.com/brownjuly2003-code/NL_SQL/raw/main/docs/ui-live-demo.mp4
5858

5959
## Quick start
6060

61+
Two tiers: **(A) clone-first** (fastest first run) and **(B) full local rebuild** (all 12 DBs).
62+
63+
### A. Clone-first (fastest)
64+
65+
Requires **Python 3.13**.
66+
67+
A tracked clone already includes **9 SQLite DBs** (chinook + 8 BIRD slices under GitHub's size limit) plus a **prebuilt Chroma** index in `chroma_data/`. No download or reindex is needed for the first run.
68+
6169
```powershell
6270
# 1. Sync deps (incl. UI)
63-
make install-ui # or: uv sync --extra dev --extra ui
71+
uv sync --extra dev --extra ui
72+
# or: make install-ui
73+
74+
# 2. Env file — supply your own MISTRAL_API_KEY in `.env`
75+
Copy-Item .env.example .env # PowerShell
76+
# cp .env.example .env # Unix / Git Bash
77+
78+
# 3. Launch the chat UI
79+
uv run streamlit run app/streamlit_app.py
80+
# or: make ui
81+
```
6482

65-
# 2. Download data (one-time)
83+
`MISTRAL_API_KEY` is required for embeddings (`mistral-embed`) even if SQL generation uses `GITHUB_TOKEN`, `GROQ_API_KEY`, or Ollama. Supply your own Mistral key; external API calls are subject to your provider quotas (not claimed free here).
84+
85+
Postgres is optional (local/CI). The public HF Space is SQLite-only.
86+
87+
### B. Full local rebuild (12 DBs)
88+
89+
Download data and rebuild the schema index for all 12 DBs:
90+
91+
```powershell
92+
# Download data (one-time)
6693
uv run python scripts/download_data.py chinook
6794
uv run python scripts/download_data.py bird-mini-dev
6895
69-
# 3. Build the schema index (one-time, ~2 min for all 12 DBs)
96+
# Build the schema index (one-time, ~2 min for all 12 DBs)
7097
uv run python scripts/build_index.py --db all
71-
72-
# 4. Launch the chat UI
73-
make ui # or: uv run streamlit run app/streamlit_app.py
7498
```
7599

76-
The UI reads `MISTRAL_API_KEY` from `.env`; copy `.env.example` first.
100+
Then launch the UI as in (A).
77101

78102
Публичный демо — Hugging Face Space (Docker). Как он деплоится (tracked-only + prune),
79103
см. [`DEPLOY.md`](DEPLOY.md).

‎tests/test_readme_local_first.py‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
"""README Quick start contract: clone-first vs full rebuild (pathlib-only)."""
2+
3+
from __future__ import annotations
4+
5+
from pathlib import Path
6+
7+
REPO_ROOT = Path(__file__).resolve().parents[1]
8+
README = REPO_ROOT / "README.md"
9+
10+
11+
def _quick_start_through_documentation() -> str:
12+
"""Slice from ``## Quick start`` up to the next H2."""
13+
text = README.read_text(encoding="utf-8")
14+
start = text.index("## Quick start")
15+
end = text.index("\n## ", start + 1)
16+
return text[start:end]
17+
18+
19+
def test_readme_quick_start_local_first_contract() -> None:
20+
section = _quick_start_through_documentation()
21+
22+
assert "Python 3.13" in section
23+
24+
assert "cp .env.example .env" in section
25+
assert "Copy-Item .env.example .env" in section
26+
27+
assert "MISTRAL_API_KEY" in section
28+
assert "your own Mistral key" in section
29+
assert "not claimed free" in section
30+
assert "free-tier" not in section.lower()
31+
assert "$0" not in section
32+
33+
assert "9 SQLite DBs" in section
34+
assert "prebuilt Chroma" in section
35+
assert "No download or reindex is needed for the first run" in section
36+
37+
assert "uv run python scripts/download_data.py chinook" in section
38+
assert "uv run python scripts/download_data.py bird-mini-dev" in section
39+
assert "uv run python scripts/build_index.py --db all" in section
40+
41+
assert "required for embeddings" in section
42+
assert "GITHUB_TOKEN" in section
43+
assert "GROQ_API_KEY" in section
44+
assert "Ollama" in section
45+
46+
assert "Postgres is optional" in section
47+
assert "SQLite-only" in section
48+
49+
assert "uv sync --extra dev --extra ui" in section
50+
assert "uv run streamlit run app/streamlit_app.py" in section

0 commit comments

Comments
 (0)