README.md

metadata

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

---

📌 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):

curl -X POST -F "[email protected]" https://<space>.hf.space/upload

📤 GET /connections

Lista todas las bases subidas.

📤 GET /schema/{connection_id}

Devuelve el esquema en formato Spider-like:

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.

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

🧱 Arquitectura

Genera SQL, lo ejecuta, repara si es necesario y retorna resultados.

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)