Add comprehensive README

README.md

@@ -1,12 +1,106 @@
 ---
-title: Text To Sql Agent
-emoji: 🌍
-colorFrom: gray
+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
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🗃️ 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