Skip to content

NL2SQL 0.2.0

The hosted demo release: try NL2SQL in a browser, without a key or with your own, or run the same playground locally with pip install "nl2sql-engine[demo]".

Released 2026-10-10.

Highlights

  • A public demo on Hugging Face Spaces (https://nadeem4nk-nl2sql-demo.hf.space). It asks three linked sample databases in plain English and shows the plan, the checks, the SQL and the rows.
  • No key needed to start. Twenty guided questions replay real recorded answers. For anything else, bring your own key; it stays in your browser tab and is used for that one request only.
  • pip install "nl2sql-engine[demo]" and nl2sql demo run the same playground on your machine. It has a home page, an answer-first Ask page, a Pipeline page and a Retrieval inspector.
  • Claude is supported natively alongside OpenAI-compatible providers, and each step can use its own model.
  • A release now runs end to end on its own: tag, PyPI, a fresh install check, then the Space at the same version.

What's included

Features

  • Hosted mode: a public demo where each visitor brings their own key and the server holds none (#165), plus the Dockerfile and Space config to run it (#168).
  • Try the hosted demo without a key, on recorded runs (#197), with real recorded answers for the 20 guided questions (#205).
  • The React playground and nl2sql demo (#93), now with a home page (#198), an answer-first Ask page (#186) and a Pipeline page (#171).
  • Support and web-analytics sample databases, linked to Chinook customers (#157).
  • Native Claude support, and a provider per pipeline step (#124). In the hosted demo, each step can use its own model, with a key per provider (#173).
  • QueryResult exposes the plan, the validation checks, a row sample, the status and timings (#88).
  • Every run can be recorded to a trace file, viewed, and replayed without the model (#104).
  • Validated plans are cached by question and schema version, and checked again on every use (#122).
  • An evaluation harness: a Chinook gold dataset (#114), a tier 1 check on every PR (#119) and a tier 2 benchmark against real models (#126).
  • Each tagged release deploys the Space, pinned to the version on PyPI (#196).

Fixes

  • The validator rejects a plan whose tables cannot be joined before SQL is generated, so the model can try again (#161). Only known function names are allowed in plans (#137).
  • Role checks refuse without leaking data from forbidden tables, and deny unknown or empty roles cleanly (#112).
  • API keys and connection secrets are held as SecretStr, so they never print (#113).
  • When a sub-query fails, you get a structured result, not a crash or a loop (#84). The pipeline timeout is enforced (#87).
  • The aggregator combines sub-query results correctly when join keys carry a prefix (#144, #162).
  • Many smaller fixes to the generator, the decomposer, the CLI and the demo. See the changelog below.

Docs

  • The README is organised around a quickstart, results, the CLI, the REST API and screenshots (#131), and links the live demo (#191).

Known limits

  • No API image was published to GHCR for 0.2.0: its Dockerfile used Python 3.11. The first Space deploy also failed, on a PyPI index that had not caught up. Both are fixed in 0.2.1.
  • Without a key, the hosted demo only answers the 20 guided questions it has recordings for.
  • A question that needs several sub-queries can be answered wrong without an error. 0.2.2 fixes the known cases.

Upgrading

pip install --upgrade "nl2sql-engine[demo]==0.2.0"

Breaking changes: Chinook is now the only demo dataset. nl2sql setup --demo --lite, --demo --docker and nl2sql demo --dataset are removed, and nl2sql setup --demo sets up Chinook (#98).

What's next

Next: 0.2.1, which fixes the release image and makes the Space deploy reliable.

Full changelog: v0.1.2...v0.2.0