SQLSense

A safe, self-correcting natural-language-to-SQL assistant for a Chinook-style database.

Accuracy

Verified accuracy on the current golden set: 22/22 = 100.0% (22 questions, deterministic fallback mode).

Architecture

Question -> LLM Planner -> Safety Guard -> Execution -> Self-Correction (if needed) -> Answer

Design decisions

• ADR-0001: Deterministic safety guard for SQL execution
• ADR-0002: Groq as a development bridge to local models
• ADR-0003: Eval-first development

Current limitations & roadmap

1. Migrating from Groq to local models (Ollama) is the immediate next step.
2. Accuracy is a baseline on a small golden set, not yet BIRD-benchmarked at scale.
3. No persistent memory across sessions yet.
4. Single-agent workflow currently; agentic multi-tool system is next phase.

Setup

1. Create and activate a Python environment.
2. Install dependencies:

   pip install -e .[dev]

3. Start the app with a local database URL or the sqlite fallback:

   $env:DATABASE_URL='sqlite:///c:/Users/hp/sqlsense/.tmp_sqlsense.db'
   $env:SQLSENSE_TEST_MODE='1'
   uvicorn sqlsense.api.main:app --host 127.0.0.1 --port 8000

4. Open http://127.0.0.1:8000/ to use the browser UI.

Evaluation

Run the evaluator with:

$env:DATABASE_URL='sqlite:///c:/Users/hp/sqlsense/.tmp_sqlsense.db'
$env:SQLSENSE_TEST_MODE='1'
python -m eval.run_eval

Screenshot placeholder