CoolFace
Apppublic

k1golestan/text-to-sql-agent

sourceHugging Facemitupdated 5mo agoView on Hugging Face
0likes
App README

🗃️ 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. 1.Classify — Is the question answerable, ambiguous, or unanswerable?
  2. 2.Clarify — If ambiguous, ask the user targeted questions before generating SQL
  3. 3.Execute & Verify — Generate SQL, run it, self-correct if errors occur

🧪 Try These Examples

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

PaperKey Contribution
MMSQL4-type question classification (answerable/ambiguous/unanswerable/improper)
PRACTIQMulti-turn clarification dialogue patterns for SQL
SQLFixAgentSelf-correcting SQL via ReAct reasoning
MTSQL-R1Agentic multi-turn SQL with memory verification
Disambiguate-then-ParseInterpretation generation for ambiguous queries

🔧 Technical Stack

  • —Agent: 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