Chat SQL con LangChain + Amazon Bedrock

Asistente conversacional para analizar datos de ventas en lenguaje natural. Convierte preguntas en SQL seguro (solo SELECT) con LangChain + Amazon Bedrock, ejecuta sobre SQLite local y devuelve tabla, gráfico o archivo (CSV/Excel). UI en Streamlit y API en FastAPI.

---

Requisitos

• Python 3.10+
• Cuenta y credenciales AWS con acceso a Amazon Bedrock (modelo de conversación habilitado).
• Sistema operativo con gcc/build-essential (recomendado para algunas dependencias).
• (Opcional) virtualenv.

# Crear y activar entorno
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate

# Instalar dependencias
pip install -r requirements.txt

---

Configuración (.env)

Crea un archivo .env en la raíz del repo con las variables:

# Rutas de datos (puedes dejarlas por defecto)
CSV_PATH=app/data/ventas.csv
DB_PATH=app/data/ventas.db

# AWS / Bedrock
AWS_REGION=us-east-1
BEDROCK_MODEL_ID=anthropic.claude-3-5-sonnet-20240620-v1:0  # Ejemplo; usa el que tengas habilitado

# Seguridad (lista blanca de tablas; vacío = permitir todas las detectadas)
ALLOWED_TABLES=ventas

# Límite máximo de filas retornadas por consulta
MAX_ROWS=200

# Frontend
API_HOST=http://127.0.0.1:8000

Configura tus credenciales de AWS por cualquiera de los métodos estándar (perfil por defecto ~/.aws/credentials, variables de entorno, etc.).

---

▶Cómo ejecutar

1) Backend (FastAPI)

uvicorn app.main:app --reload --port 8000

• Documentación interactiva: http://127.0.0.1:8000/docs
• Carpeta de exportaciones (imágenes/CSV/Excel): app/data/exports

2) Frontend (Streamlit)

En otra terminal con el mismo entorno activado:

streamlit run streamlit_app.py

Si necesitas apuntar a otro host/puerto del backend, cámbialo desde la barra lateral (campo API Host).

---

Estructura de carpetas (principal)

app/
  data/
    ventas.csv          # Dataset por defecto
    ventas.db           # SQLite generado (auto)
    exports/            # Resultados: charts .png y archivos .csv/.xlsx
  utils/
    db_utils.py         # Utilidades de base de datos (CSV → SQLite)
  main.py               # API FastAPI (backend)
streamlit_app.py        # UI Streamlit (frontend)
requirements.txt
README.md
.env                    # (no versionar)

---

¿Qué hace cada archivo?

app/main.py – Backend/API

• Carga .env, rutas y parámetros (límite de filas, lista blanca de tablas, etc.).
• Convierte ventas.csv a SQLite (ventas.db) al iniciar (si no existe) mediante csv_to_sqlite.
• Conecta SQLDatabase (LangChain) a SQLite.
• Inicializa el LLM de Bedrock para generar SQL y respuestas en lenguaje natural.
• Seguridad: bloquea DDL/DML (DROP/DELETE/UPDATE/INSERT/ALTER/CREATE) y aplica LIMIT automático; opcionalmente verifica ALLOWED_TABLES.
• Prompts:
  • SQL prompt: genera solo la consulta SQL (sin explicaciones); si necesita monto/ingresos usa cantidad*precio con alias.
  • NL prompt: redacta una respuesta de negocio breve (top 1 / top 3, manejo de “sin filas”).
• Detección de intención: tabla, gráfico (barras/líneas/pastel) o archivo (CSV/XLSX).
• Render: crea gráficos con Matplotlib (modo Agg) y archivos; expone la carpeta /exports.
• Endpoints:
  • GET / estado básico y rutas.
  • GET /health estado de la base.
  • GET /schema esquema y preview (10 filas).
  • POST /chat cuerpo: { "question": "..." } → SQL, respuesta NL y salida (tabla/gráfico/archivo).
  • POST /upload_csv permite subir un CSV y regenerar la base SQLite al vuelo.

app/utils/db_utils.py

• Función csv_to_sqlite(csv_path, db_path):
  • Lee el CSV (UTF‑8) y lo inserta en una base SQLite con tabla ventas (crea directorios si faltan).
  • Sobrescribe la base cuando se sube un nuevo CSV desde /upload_csv.

streamlit_app.py – Frontend/UI

• Formulario para API Host (cambiar backend) y carga de CSV (sube al endpoint /upload_csv).
• Botón “Ver esquema y preview”: consulta /schema y muestra el esquema + 10 filas.
• Campo de texto para preguntas en lenguaje natural y botón Consultar:
  • Llama POST /chat y muestra:
    • Respuesta en lenguaje natural.
    • SQL generado.
    • Tabla (si la intención fue table o no hubo formato especificado).
    • Gráfico (renderiza imagen alojada en /exports).
    • Archivo descargable (muestra URL de /exports/...).
• Historial de respuestas en acordeones (la más reciente aparece abierta).

---

Seguridad y buenas prácticas

• Solo se ejecutan consultas SELECT y se añade LIMIT automático (MAX_ROWS).
• Palabras bloqueadas: DROP, DELETE, UPDATE, INSERT, ALTER, CREATE.
• (Opcional) Lista blanca de tablas con ALLOWED_TABLES (coma-separado).
• Revisa siempre el SQL mostrado antes de confiar en resultados para auditorías/decisiones críticas.

---

Cambiar el dataset

1. En la barra lateral del frontend, sube un nuevo CSV con las columnas adecuadas (por ejemplo: id, vendedor, sede, producto, cantidad, precio, fecha).
2. El backend regenerará ventas.db y el frontend quedará listo para consultar el nuevo esquema.

---

Ejemplos de preguntas

• “¿Qué sede vendió más cantidad el último mes? muéstralo en gráfico de barras.”
• “Top 3 vendedores por ingresos totales (usa cantidad*precio).”
• “Dame tabla con ventas por producto y sede.”
• “Exporta a Excel los ingresos diarios de septiembre.”

Puedes añadir palabras clave como tabla / gráfico / barras / líneas / pastel / CSV / Excel para orientar la salida.

---

Prueba rápida (local)

1. Lanza backend y frontend como arriba.
2. En Streamlit, haz una pregunta como:
   • “¿Cuál es el vendedor con más ingresos? (muestra en tabla)”
   • “Muéstrame los ingresos por sede en gráfico de pastel.”
3. Verifica que aparezcan:
   • La respuesta de negocio, el SQL, y según el caso tabla / gráfico / enlace de descarga.

---

Troubleshooting

• Bedrock no configurado: revisa BEDROCK_MODEL_ID, AWS_REGION y credenciales AWS activas.
• No se pudo generar el gráfico: puede faltar una columna numérica; comprueba que tu pregunta derive una métrica (p. ej., SUM(cantidad*precio)).
• Permisos denegados al escribir en app/data/exports: verifica permisos del sistema y que la carpeta exista.
• Unicode/encoding en CSV: guarda tu CSV como UTF‑8 (con BOM opcional).

---

Licencia

MIT (ajusta según tu proyecto).