Spaces:
Sleeping
Sleeping
File size: 3,703 Bytes
2e5ff2b 5a17891 2e5ff2b 5a17891 2e5ff2b 5a17891 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 | ---
title: Multi-Turn Text-to-SQL Agent
emoji: 🗃️
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 6.13.0
app_file: app.py
pinned: false
license: mit
tags:
- text-to-sql
- agent
- smolagents
- multi-turn
- clarification
---
# 🗃️ Multi-Turn Text-to-SQL Agent with Clarification
An intelligent SQL assistant that doesn't just generate SQL — it **thinks before querying**. When your question is ambiguous, it asks for clarification first. When data doesn't exist, it tells you why and suggests alternatives.
## 🎯 What Makes This Different
Traditional text-to-SQL systems blindly generate a query from your question. This agent follows a **3-step decision process** inspired by recent research:
1. **Classify** — Is the question answerable, ambiguous, or unanswerable?
2. **Clarify** — If ambiguous, ask the user targeted questions before generating SQL
3. **Execute & Verify** — Generate SQL, run it, self-correct if errors occur
## 🧪 Try These Examples
| Query | Expected Behavior |
|-------|------------------|
| `"Show me the top employees"` | 🤔 **Asks clarification** — Top by salary? Orders handled? Tenure? |
| `"Which customer spent the most?"` | ✅ **Answers directly** with SQL JOIN across orders/customers |
| `"What's the customer satisfaction score?"` | ❌ **Explains** the data doesn't exist, suggests alternatives |
| `"By salary, in Engineering"` (after ambiguous Q) | ✅ **Remembers context** and answers the clarified question |
## 🏗️ Architecture
```
User Question
│
▼
┌─────────────────────┐
│ Intent Classifier │ ← Answerable / Ambiguous / Unanswerable
└─────────┬───────────┘
│
┌─────┼─────┐
▼ ▼ ▼
Clear Ambig N/A
│ │ │
▼ ▼ ▼
SQL Ask Explain
Gen Clarify Why
│ │
▼ ▼
Execute User
DB Reply
│ │
▼ └──→ (next turn)
Results
```
## 📊 Demo Database
The Space comes with a pre-loaded **company database** (6 tables, ~60 rows):
- **departments** — Engineering, Sales, Marketing, HR, Finance
- **employees** — 12 employees with salary, hire date, department, manager
- **customers** — 8 B2B customers with tiers (standard/premium/enterprise)
- **products** — 8 products (Hardware/Software) with price, cost, stock
- **orders** — 12 orders with status (completed/shipped/pending/cancelled)
- **order_items** — 17 line items with quantity, price, discount
## 📚 Research Foundation
This agent's design draws from:
| Paper | Key Contribution |
|-------|-----------------|
| [MMSQL](https://arxiv.org/abs/2412.17867) | 4-type question classification (answerable/ambiguous/unanswerable/improper) |
| [PRACTIQ](https://arxiv.org/abs/2410.11076) | Multi-turn clarification dialogue patterns for SQL |
| [SQLFixAgent](https://arxiv.org/abs/2406.13408) | Self-correcting SQL via ReAct reasoning |
| [MTSQL-R1](https://arxiv.org/abs/2510.12831) | Agentic multi-turn SQL with memory verification |
| [Disambiguate-then-Parse](https://arxiv.org/abs/2502.18448) | Interpretation generation for ambiguous queries |
## 🔧 Technical Stack
- **Agent**: [smolagents](https://huggingface.co/docs/smolagents) `CodeAgent` with ReAct loop
- **LLM**: Qwen/Qwen2.5-Coder-32B-Instruct via HF Inference API
- **Database**: SQLite (in-memory demo)
- **UI**: Gradio chat interface with multi-turn support
## 🚀 Run Locally
```bash
pip install smolagents[gradio] sqlalchemy
export HF_TOKEN=your_token_here
python app.py
```
## License
MIT
|