---
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