README.md

---
title: NL2SQL Backend T5
emoji: 🧠
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: mit
---

# NL2SQL Backend T5 (Spider)

Backend universal NL→SQL basado en T5-Large entrenado en Spider, con soporte para:
- Subida de bases de datos SQLite / SQL / CSV / ZIP
- Conversión automática de cualquier BD a SQLite
- Construcción dinámica de esquema
- Traducción ES→EN automática
- Re-ranking de candidatos
- SQL Repair Layer (tablas/columnas inexistentes)
- Endpoint `/infer` totalmente listo para producción
- Implementado para HuggingFace Spaces con Docker

# 🚀 NL→SQL Universal Backend (FastAPI + T5-large Spider)
**Autores:** Steven Reátegui licham y Danna Medina Villena  
**Modelo:** `stvnnnnnn/t5-large-nl2sql-spider`  
**API:** FastAPI (Docker)  
**Versión:** v1.0.0  

![FastAPI](https://img.shields.io/badge/API-FastAPI-009688?logo=fastapi)
![HuggingFace](https://img.shields.io/badge/Hosted%20on-HuggingFace-yellow?logo=huggingface)
![SQL](https://img.shields.io/badge/Engine-SQLite-blue)
![Model](https://img.shields.io/badge/Model-T5--Large%20Spider-orange)

---

## 📌 Descripción

Este Space implementa un **backend universal NL→SQL**, capaz de:

- Recibir preguntas en **lenguaje natural** (español o inglés).  
- Convertirlas a **SQL** usando el modelo T5-large fine-tuned en Spider.  
- Ejecutar la consulta sobre **cualquier base de datos que el usuario suba**:
  - `.sqlite` / `.db`  
  - `.sql` dumps (MySQL, PostgreSQL, SQLite)  
  - `.csv`  
  - `.zip` con múltiples CSV  

🧠 El backend incluye una **SQL Repair Layer** que corrige errores del modelo (nombres de tabla/columna inexistentes, pluralización, sinónimos comunes, etc.), aumentando la **Execution Accuracy**.

📦 Todo se convierte internamente a **SQLite**, para garantizar compatibilidad universal.

---

## 🔥 Características

### ✔ Soporte universal de fuentes de datos
| Tipo | Soportado | Conversión |
|------|-----------|------------|
| SQLite (.sqlite / .db) | ✅ | Usado tal cual |
| SQL dump (.sql) | ✅ | Convertido a SQLite (best-effort) |
| CSV (.csv) | ✅ | Importado como tabla |
| ZIP con CSV | ✅ | Cada CSV → tabla en SQLite |

---

### ✔ Traducción automática ES → EN
Si escribes en español, el backend detecta el idioma y traduce con **Helsinki-NLP/opus-mt-es-en** antes de enviarlo al modelo NL→SQL.

---

### ✔ SQL Repair Layer (SRL)
Corrige errores típicos:

- `no such table: Songs` → `Track`
- `no such column: Length` → `Milliseconds`
- Singularización inteligente: songs → song → track
- Matching difuso (`difflib`)
- Diccionario de sinónimos (song, track, length…)

---

### ✔ Multi-query generation + Re-ranking
Se generan **6 SQL candidatos** y se selecciona el mejor según:

1. ¿Ejecuta sin error?  
2. ¿Tiene mejor score del modelo?  
3. ¿Luego de reparar, ejecuta correctamente?  

---

## 📂 Endpoints

### 📤 `POST /upload`
Subir una base de datos.

Ejemplo (curl):
```bash
curl -X POST -F "db_file=@Chinook.sqlite" https://<space>.hf.space/upload
```

### 📤 `GET /connections`
Lista todas las bases subidas.

### 📤 `GET /schema/{connection_id}`
Devuelve el esquema en formato Spider-like:

```bash
Track(TrackId, Name, AlbumId, …) ; Album(AlbumId, Title, ArtistId) ; …
```

### 📤 `GET /preview/{connection_id}/{table}`
Vista previa de una tabla.

### 📤 `POST /infer`
Genera SQL, lo ejecuta, repara si es necesario y retorna resultados.

```bash
{
  "connection_id": "db_xxxxxx",
  "question": "Muestra los nombres de las canciones."
}
```

### 🧱 `Arquitectura`
Genera SQL, lo ejecuta, repara si es necesario y retorna resultados.

```bash
Usuario → Pregunta (ES/EN)
      → Detectar idioma
      → Traducir (si ES)
      → T5-large NL→SQL
      → SQL Repair Layer
      → Ejecución real en SQLite
      → Respuesta JSON (SQL + resultados + candidatos)
```

### 🏁 `Estado actual del proyecto`
Versión v1.0 — Backend Final
Listo para integrarse con:
      - Frontend Next.js (UI estilo chat)
      - Explorador de esquemas
      - Historial de consultas por usuario
      - Ejecución segura de SQL (solo lectura)