Skip to content

Commit 7d55c73

Browse files
committed
docs: freeze NL SQL closure scope
1 parent 57623bc commit 7d55c73

4 files changed

Lines changed: 88 additions & 15 deletions

File tree

‎DEPLOY.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11
# Deployment — Hugging Face Space (Docker)
22

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.
3+
The public Space is <https://liovina-nl-sql.hf.space>, but it is not currently a
4+
live demo. The Hugging Face API reports `PAUSED` / `Flagged as abusive`
5+
(`Cloudflared`) since 2026-07-22. Restoring or retiring the deployment is an
6+
owner-authorized closure action; the policy below describes the safe publish
7+
path if restoration is chosen.
58

69
## Deploy policy: only what git tracks, then prune
710

‎README.md‎

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,15 @@
11
# NL→SQL Assistant
22

3-
[![Live demo](https://img.shields.io/badge/live_demo-HF_Space-FF6F00?logo=huggingface&logoColor=white)](https://liovina-nl-sql.hf.space) [![CI](https://github.com/brownjuly2003-code/NL_SQL/actions/workflows/ci.yml/badge.svg)](https://github.com/brownjuly2003-code/NL_SQL/actions/workflows/ci.yml) ![Python](https://img.shields.io/badge/python-3.13-3776AB?logo=python&logoColor=white) ![BIRD Mini-Dev](https://img.shields.io/badge/BIRD_Mini--Dev-61.5%25_reproducible-brightgreen) ![License](https://img.shields.io/badge/license-MIT-blue)
3+
[![Demo paused](https://img.shields.io/badge/demo-paused-lightgrey?logo=huggingface)](https://liovina-nl-sql.hf.space) [![CI](https://github.com/brownjuly2003-code/NL_SQL/actions/workflows/ci.yml/badge.svg)](https://github.com/brownjuly2003-code/NL_SQL/actions/workflows/ci.yml) ![Python](https://img.shields.io/badge/python-3.13-3776AB?logo=python&logoColor=white) ![BIRD Mini-Dev](https://img.shields.io/badge/BIRD_Mini--Dev-61.5%25_reproducible-brightgreen) ![License](https://img.shields.io/badge/license-MIT-blue)
44

55
Portfolio demo для Senior Data Engineer / Data Analyst. Принимает вопрос на естественном языке (RU/EN), возвращает ответ из реляционной БД в одной из четырёх форм: число, предложение, таблица, график. Всегда показывает использованный SQL и объяснение. AST-guard + read-only execution + row cap — без шанса на DML/DDL побег.
66

7-
**Статус:** Stages 1–10 закрыты. Production FastAPI surface, retrieval-augmented LangGraph pipeline, редизайн Streamlit UI с EN/RU-переключателем (детали дизайна — в разделе UI ниже). Тесты, ruff и mypy --strict гоняются в CI (бейдж выше — живой). Live API verified на Mistral + Groq.
7+
**Статус:** closure candidate; Stages 1–10 закрыты и scope заморожен.
8+
Production FastAPI surface, retrieval-augmented LangGraph pipeline, редизайн
9+
Streamlit UI с EN/RU-переключателем. Тесты, ruff и mypy --strict гоняются в CI.
10+
Финальные критерии: [docs/PROJECT_CLOSURE.md](docs/PROJECT_CLOSURE.md).
11+
Публичный HF Space сейчас `PAUSED` / `Flagged as abusive` (`Cloudflared`), поэтому
12+
live-доступ не заявляется.
813

914
**Headline metric — два воспроизводимых уровня (BIRD Mini-Dev SQLite, n=200, $0 free-tier)**
1015

@@ -34,7 +39,7 @@ uv run python scripts/eval_baseline.py --config E --n 200 --bird-rescue-hints
3439

3540
Полная по-версионная lift-трасса, saturation-evidence и audit-методология — в [docs/03_eval_methodology.md](docs/03_eval_methodology.md).
3641

37-
**UI (2026-06-16 редизайн, anti-slop):** Streamlit chrome переписан в editorial-warm светлый стиль — тёплая stone-палитра на белом, один акцент terracotta (`#C2541B`, без сине-фиолетового SaaS-дефолта), self-hosted **Manrope** (UI + tabular figures, полная кириллица) и **JetBrains Mono** (SQL), скруглённые углы по единой шкале (12/8/pill), тёплые тени. Контролы вынесены в закреплённый (sticky) верхний бар: база, режим и переключатель EN↔RU. В сайдбаре остались только schema explorer, advanced retrieval и clear chat — без скролла. Hero + две stat-карточки + свёрнутый блок методологии. Контраст текста/кнопок/ссылок проверен на WCAG AA, focus-ring на всех интерактивных элементах. Без эмодзи и стоковых иконок. Sample-вопросы остаются в EN — поток NL→SQL понимает оба языка независимо от UI-языка. Живой Space `liovina-nl-sql.hf.space` задеплоен на этот дизайн; скриншоты ниже пересняты с live.
42+
**UI (2026-06-16 редизайн, anti-slop):** Streamlit chrome переписан в editorial-warm светлый стиль — тёплая stone-палитра на белом, один акцент terracotta (`#C2541B`, без сине-фиолетового SaaS-дефолта), self-hosted **Manrope** (UI + tabular figures, полная кириллица) и **JetBrains Mono** (SQL), скруглённые углы по единой шкале (12/8/pill), тёплые тени. Контролы вынесены в закреплённый (sticky) верхний бар: база, режим и переключатель EN↔RU. В сайдбаре остались только schema explorer, advanced retrieval и clear chat — без скролла. Hero + две stat-карточки + свёрнутый блок методологии. Контраст текста/кнопок/ссылок проверен на WCAG AA, focus-ring на всех интерактивных элементах. Без эмодзи и стоковых иконок. Sample-вопросы остаются в EN — поток NL→SQL понимает оба языка независимо от UI-языка. Скриншоты ниже сняты с ранее работавшего Space; текущий Space paused.
3843

3944
| EN | RU |
4045
|:--:|:--:|
@@ -54,7 +59,9 @@ https://github.com/brownjuly2003-code/NL_SQL/raw/main/docs/ui-live-demo.mp4
5459
- Diagnostic harness: `scripts/error_taxonomy.py` классифицирует провалы (filter_or_value / row_count_off / order_by_off / exec_failed / empty) для целевой работы с конкретными bucket'ами.
5560
- Provider abstraction под Mistral / Groq / GitHub Models / Ollama / Perplexity browser bridge — модель меняется без переписывания пайплайна.
5661

57-
**Live demo:** <https://liovina-nl-sql.hf.space> (Hugging Face Spaces, Docker runtime, free tier). Cold start ~30 c при первом заходе, дальше interactive. Default DB — `bird_california_schools`; в sidebar можно переключить на любую из 9 shipped DBs (chinook + 8 BIRD).
62+
**Deployment status:** public Space <https://liovina-nl-sql.hf.space> существует,
63+
но сейчас paused/flagged и не является live demo. Когда Space работал, default DB
64+
была `bird_california_schools`, а selector содержал 9 shipped DBs.
5865

5966
## Quick start
6067

‎docs/BACKLOG.md‎

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,17 @@
33
Single living tracker for code/eval work items. Supersedes the scattered per-audit
44
lists — new findings land here with a status so nothing rots undone.
55

6-
Status: ✅ done · ⛔ gated (needs a human decision or an external host) · 🔎 won't-fix (verified)
6+
Status: ✅ done · ⛔ external/future · 🔎 won't-fix · 🧊 frozen
7+
8+
## Closure disposition (2026-07-27)
9+
10+
Текущий product scope заморожен; все безопасные локальные обязательства закрыты.
11+
Секции research pass и `Next levers` ниже сохранены как evidence и future ideas,
12+
а не как активная очередь. Внешние host/key/pen-test пункты также не являются
13+
незакрытым local-first claim.
14+
15+
Полный closing scope, сохранённый локальный WIP и обязательные publish/Space
16+
гейты: [PROJECT_CLOSURE.md](PROJECT_CLOSURE.md).
717

818
## Done (2026-07-11)
919

@@ -46,7 +56,7 @@ The code written during the two passes above had not itself been reviewed. Five
4656
- ✅ **The comparator scored correct answers as misses (int vs float).** `_hashable` quantised floats onto the tolerance grid but passed ints through untouched: gold `5` hashed to `5`, pred `5.0` to `5_000_000`, and the set comparison called it a mismatch. That is *stricter than BIRD's own scorer*, which sets raw Python tuples — where `5 == 5.0` collapses — and it contradicted the apples-to-apples claim in the docstring. The ordered path compares through a tolerance and always got these right, so one (gold, pred) pair scored two different ways depending on whether gold had `ORDER BY`. Every number — int, float, and (post-`_normalise_cell`) Decimal — now shares one grid. Re-measured: **SQLite n=200 → 58.0% (116/200), up from 57.5%**; the recovered question is a `challenging` one (41.2% → 44.1%). Postgres n=49 unchanged (49.0%), SQLite control n=49 unchanged (44.9%), Chinook still 100%. The fix is monotone — it can only merge buckets that were wrongly split — so no previously-passing question can regress.
4757
- ✅ **Engine leak on the hot path.** `DatabaseSpec.make_engine()` called `create_engine` on *every* invocation — once per `/ask`, once per eval question — so no pool was ever reused and none disposed, while `connect()`'s docstring promised reuse. On Postgres that opens a fresh backend per question and walks straight into `max_connections` under sustained load. Engines are built once per spec and pooled now (`dispose_engines()` clears the cache). Paired fix: the SQLite statement-timeout progress handler is disarmed on the way out — pooled connections get handed to the next caller (schema introspection never arms one of its own), and a handler left behind carries an already-expired deadline that would interrupt that caller's first non-trivial query.
4858

49-
## In progress — lifting the reproducible number (2026-07-11)
59+
## Closed research pass — lifting the reproducible number (2026-07-11)
5060

5161
The reproducible single-run is the only number that matters here: 58.0% at the
5262
start of this pass. Every step below is measured on the same n=200 BIRD Mini-Dev
@@ -96,14 +106,12 @@ retrieve descriptions only for the columns a question plausibly touches.
96106
Rule of thumb this pass earned: **space at the top of the prompt is a scarce
97107
resource, and any lever that lengthens the prompt must pay for the room it takes.**
98108

99-
## Next levers (research, 2026-07-12 — see `docs/quality_levers_research_2026-07.md`)
109+
## Retired/future research ideas (2026-07-12 — see `docs/quality_levers_research_2026-07.md`)
100110

101111
After the lever-exhaustion day (eight levers measured dead or parity), three
102-
research passes mapped what is left: training-free techniques through July 2026,
103-
free API tiers, and a completeness sweep over the established named systems
104-
(DIN/DAIL/C3/MAC/PET/TA/E-SQL/RSL/MCS/CHASE/OpenSearch/Alpha/XiYan + the
105-
NL2SQL360 taxonomy). Ranked worklist — every measurement is a full n=200,
106-
flag-gated, one lever per run:
112+
research passes mapped possible follow-on work. This historical ranked list is
113+
closed with the current project and requires a separately authorized research
114+
project before any new run:
107115

108116
- ⛔ **Gemini 3 Flash as generator** — AI Studio free tier fits n=200 in a day
109117
(1,500 req/day, no card); `_openai_compat.py` already speaks the protocol.
@@ -136,7 +144,7 @@ ceiling-anatomy write-up. Side-fact for the latter: ReViSQL's BIRD-Verified
136144
found defects in 61.1% of BIRD Train instances — a second team independently
137145
confirming the annotation-noise thesis behind the ~61–62% free-stack ceiling.
138146

139-
## Gated (needs a decision or an external host)
147+
## External/future items — not active product backlog
140148

141149
- ⛔ **Sustained-load benchmark.** The data-migration half is done (above); a throughput/latency run under sustained load still wants a host that isn't the Windows dev box.
142150
- ⛔ **Space cleanup + git history.** `SESSION_HANDOFF.md` is un-tracked now, so future deploys won't republish it; removing it from the live Space and any git-history rewrite are force/deploy actions — owner's call.

‎docs/PROJECT_CLOSURE.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Project closure
2+
3+
Дата фиксации scope: 2026-07-27.
4+
5+
## Закрываемый scope
6+
7+
Финальный scope — Stages 1–10 из публичного README:
8+
9+
- RU/EN NL→SQL pipeline и четыре формата ответа;
10+
- SQLite product path и проверенный PostgreSQL read-only path;
11+
- AST guard, statement timeout, row cap, API auth/rate limit;
12+
- reproducible BIRD baseline 61.5%, Chinook workload 60/60 и честно отделённые
13+
eval-only результаты;
14+
- Streamlit UI, FastAPI surface, CI, docs и clone-first local setup.
15+
16+
После финальной публикации этот scope feature-frozen. Улучшение benchmark score,
17+
новые модели и исследовательские методы требуют нового отдельно
18+
санкционированного проекта.
19+
20+
## Backlog disposition
21+
22+
- `docs/BACKLOG.md` остаётся living record, но секции прежнего research pass и
23+
`Next levers` теперь являются историей и `future`, а не активной очередью.
24+
- CHESS/DAIL/CHASE/E-SQL, synthetic few-shot, query-plan CoT, новые generator
25+
keys и дальнейшие BIRD score campaigns закрыты как исследовательский scope.
26+
- Sustained-load host и внешний pen-test переведены в `future operations`; они
27+
не являются незавершённым local-first product claim.
28+
- Provider-neutral local embeddings — отдельный будущий архитектурный проект,
29+
не residual закрываемой версии.
30+
31+
Ни один research-пункт не объявляется реализованным: он выведен из текущего
32+
scope явно.
33+
34+
## Обязательные внешние closure gates
35+
36+
- closing commits опубликованы в `main`, CI зелёный на точном SHA;
37+
- принято финальное решение о версии/tag/release для текущего `0.1.0`;
38+
- Hugging Face Space `liovina/nl-sql`, который с 2026-07-22 имеет состояние
39+
`PAUSED` / `Flagged as abusive` (`Cloudflared`), либо восстановлен и проверен
40+
на closing SHA, либо публично снят с эксплуатации;
41+
- после решения по Space публичные README/DEPLOY claims совпадают с фактом.
42+
43+
Push, release и deploy/Space mutations требуют явного разрешения владельца.
44+
45+
## Сохранённый локальный WIP
46+
47+
Без изменений сохранены:
48+
49+
- `.gitignore` (`/for_ju.txt`);
50+
- два tracked Chroma binary-файла;
51+
- `eval/reports/2026-07-16/index.html`;
52+
- `NL-SQL Explainer.html`, `bird_issues*.txt` и untracked eval reports.
53+
54+
Эти файлы не входят в closing commit и не считаются закрытым продуктовым
55+
backlog.

0 commit comments

Comments
 (0)