DEV Community: JhonyVargas

Cómo construir y desplegar un dashboard de datos con Streamlit, GitHub Actions y Streamlit Community Cloud

JhonyVargas — Wed, 09 Sep 2026 19:18:32 +0000

Casi todos los tutoriales de dashboards terminan en streamlit run app.py y una captura de pantalla. El problema es que ahí no hay nada desplegado, nada probado y nada automatizado: es una demo local que muere cuando cierras la terminal.

En este artículo construyo un dashboard real y lo llevo hasta el final: código en un repositorio público, tests que corren solos en cada push, y la app publicada en una nube pública que se redespliega sola. Sin pasos manuales de subida.

📦 Repositorio: https://github.com/JhonyVargas/global-insights-dashboard
🚀 Demo en vivo: https://global-insights-dashboard.streamlit.app

Qué vamos a construir

Un dashboard llamado Global Development Insights que explora tres indicadores de desarrollo — esperanza de vida, PBI per cápita y población — para ~140 países entre 1952 y 2007.

Tiene KPIs agregados, un mapa mundial, un bubble chart animado, rankings, series temporales y una matriz de correlación. Todo filtrable por año, continente y país.

El stack, y por qué

Pieza	Herramienta	Por qué
Framework	Streamlit	Convierte un script de Python en una web app. Cero HTML/CSS/JS.
Gráficos	Plotly Express	Interactivos por defecto (zoom, hover, animación) en una línea de código.
Datos	Pandas	El estándar para transformar datos tabulares en Python.
CI	GitHub Actions	Gratis en repos públicos, integrado al push.
Hosting	Streamlit Community Cloud	Gratis, y se conecta directo al repo de GitHub.

Una decisión clave: el dataset

Usé Gapminder, que viene incluido dentro de plotly.express:

import plotly.express as px
df = px.data.gapminder()

Esto no es pereza, es una decisión de arquitectura. El dataset viaja dentro de una dependencia que ya instalo, así que:

No hay llamadas de red en tiempo de ejecución → la app no se cae porque una API de terceros esté lenta o caída.
No hay API keys → no hay secretos que gestionar en el CI ni en el hosting.
El CI es determinista → los tests no dependen de que internet funcione dentro del runner.

Si tu proyecto sí necesita una API externa, el consejo sigue valiendo: cachea la respuesta y ten un fallback, porque tu pipeline de CI va a fallar el día que la API tenga un mal día.

Arquitectura: separa los datos de la UI

Este es el punto que más diferencia hace y el que casi nadie aplica en los tutoriales.

La tentación con Streamlit es escribir un app.py de 300 líneas donde la carga de datos, los filtros, los cálculos y los gráficos están todos mezclados. Funciona... hasta que quieres testearlo. Y entonces descubres que no puedes, porque para ejecutar una sola línea necesitas levantar todo el runtime de Streamlit.

La solución es aburrida y efectiva: toda la lógica de datos vive en un módulo normal de Python, sin importar Streamlit.

app.py          # solo UI de Streamlit
src/data.py     # lógica de datos, testeable de forma aislada
tests/

src/data.py no sabe que Streamlit existe:

def filter_data(
    df: pd.DataFrame,
    year: int | None = None,
    continents: list[str] | None = None,
    countries: list[str] | None = None,
) -> pd.DataFrame:
    filtered = df
    if year is not None:
        filtered = filtered[filtered["year"] == year]
    if continents:
        filtered = filtered[filtered["continent"].isin(continents)]
    if countries:
        filtered = filtered[filtered["country"].isin(countries)]
    return filtered


def compute_kpis(df_year: pd.DataFrame) -> dict:
    """KPIs agregados para un corte de un solo año."""
    if df_year.empty:
        return {"population": 0, "avg_life_exp": 0.0, "avg_gdp_percap": 0.0, "n_countries": 0}
    return {
        "population": int(df_year["pop"].sum()),
        "avg_life_exp": float(df_year["lifeExp"].mean()),
        "avg_gdp_percap": float(df_year["gdpPercap"].mean()),
        "n_countries": int(df_year["country"].nunique()),
    }

Fíjate en el if df_year.empty de compute_kpis. Ese guard existe porque el usuario puede deseleccionar todos los continentes en la barra lateral. Sin él, .mean() sobre un DataFrame vacío devuelve NaN, y el dashboard muestra "nan años" en lugar de un número.

Es el tipo de bug que solo encuentras si pruebas los casos límite — y probarlos es fácil precisamente porque esta función no necesita Streamlit para ejecutarse.

La UI: filtros y pestañas

Con la lógica fuera, app.py queda declarativo. Los filtros van a la barra lateral:

selected_year = st.sidebar.select_slider("Año", options=years, value=years[-1])
selected_continents = st.sidebar.multiselect(
    "Continentes", options=continents, default=continents
)

Los KPIs, en cuatro columnas:

df_year = filter_data(df, year=selected_year, continents=selected_continents)
kpis = compute_kpis(df_year)

col1, col2, col3, col4 = st.columns(4)
col1.metric("Países", kpis["n_countries"])
col2.metric("Esperanza de vida promedio", f"{kpis['avg_life_exp']:.1f} años")
col3.metric("PBI per cápita promedio", f"${kpis['avg_gdp_percap']:,.0f}")
col4.metric("Población total", f"{kpis['population']:,}")

Y las visualizaciones se reparten en pestañas, lo que evita el scroll infinito:

tab_map, tab_bubble, tab_ranking, tab_trend, tab_corr = st.tabs(
    ["🗺️ Mapa mundial", "🫧 Bubble chart", "🏆 Rankings", "📈 Tendencias", "🔗 Correlaciones"]
)

El mapa mundial es una sola llamada, porque Gapminder ya trae la columna iso_alpha con el código ISO de cada país:

with tab_map:
    fig_map = px.choropleth(
        df_year,
        locations="iso_alpha",
        color=map_metric,
        hover_name="country",
        color_continuous_scale="Viridis",
    )
    st.plotly_chart(fig_map, use_container_width=True)

Y el bubble chart animado — el gráfico clásico de Hans Rosling — sale con el parámetro animation_frame:

fig_bubble = px.scatter(
    df_bubble,
    x="gdpPercap", y="lifeExp",
    size="pop", color="continent",
    hover_name="country",
    animation_frame="year",
    log_x=True, size_max=60,
    range_x=[df_bubble["gdpPercap"].min() * 0.8, df_bubble["gdpPercap"].max() * 1.2],
    range_y=[df_bubble["lifeExp"].min() - 5, df_bubble["lifeExp"].max() + 5],
)

Dos detalles que importan aquí:

log_x=True, porque el PBI per cápita abarca varios órdenes de magnitud y en escala lineal todos los países pobres se apelotonan contra el eje.
Fijar range_x y range_y explícitamente. Si no lo haces, los ejes se reescalan en cada frame de la animación y el movimiento deja de ser comparable entre años — que es justo lo que el gráfico intenta mostrar.

Tests: dos niveles

Nivel 1 — la lógica de datos. Tests de pytest normales, rápidos, sin Streamlit:

def test_filter_data_by_year():
    df = load_data()
    filtered = filter_data(df, year=2007)
    assert (filtered["year"] == 2007).all()
    assert not filtered.empty

Nivel 2 — la app entera. Streamlit trae un framework de testing propio, AppTest, que ejecuta el script y te deja inspeccionar y manipular los widgets sin abrir un navegador:

from streamlit.testing.v1 import AppTest

def test_app_runs_without_exceptions():
    at = AppTest.from_file(APP_PATH, default_timeout=60).run()
    assert not at.exception
    assert len(at.metric) == 4


def test_app_handles_empty_continent_selection():
    at = AppTest.from_file(APP_PATH, default_timeout=60).run()
    at.multiselect[0].set_value([]).run()
    assert not at.exception

Ese último test es el que protege el caso límite del que hablé arriba: simula al usuario vaciando el filtro de continentes y verifica que la app no reviente. Es la clase de regresión que un test unitario de compute_kpis por sí solo no atrapa, porque el bug vive en la interacción entre el filtro y el render.

Automatización: el pipeline de CI

Aquí es donde el proyecto deja de ser un script y pasa a ser software. .github/workflows/ci.yml corre en cada push y cada pull request a main:

name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
          cache: "pip"

      - name: Install dependencies
        run: pip install -r requirements-dev.txt

      - name: Lint with ruff
        run: ruff check .

      - name: Run unit tests
        run: pytest -q

Tres etapas: lint → tests → smoke test. Las dos primeras son estándar. La tercera es la que recomiendo copiar:

      - name: Smoke test that the app boots
        run: |
          streamlit run app.py --server.headless true --server.port 8501 &
          for i in $(seq 1 15); do
            if curl -sf http://localhost:8501/_stcore/health; then
              echo "App is healthy"
              exit 0
            fi
            sleep 2
          done
          echo "App failed to become healthy in time"
          exit 1

Levanta la app de verdad en modo headless y consulta /_stcore/health, el endpoint de salud que Streamlit expone. ¿Por qué molestarse, si ya hay tests?

Porque los tests unitarios pasan aunque la app no arranque. Un import roto, una dependencia que quedó fuera de requirements.txt, un error de sintaxis en una parte del script que ningún test toca — todo eso pasa el pytest y luego explota en producción. El smoke test responde a la única pregunta que de verdad importa antes de desplegar: ¿esto levanta?

Y es barato: unas líneas de bash y unos 10 segundos de runner.

Despliegue continuo: de push a producción

Streamlit Community Cloud es gratuito para repositorios públicos y se conecta directamente a GitHub. El flujo completo:

Entra a share.streamlit.io con tu cuenta de GitHub.
Create app → Deploy a public app from GitHub.
Selecciona el repositorio, la rama main y el archivo principal (app.py).
Elige el subdominio y dale a Deploy.

Streamlit lee requirements.txt, instala las dependencias y levanta la app. A partir de ahí, cada push a main la redespliega automáticamente — no hay build manual, ni subir archivos, ni un deploy.sh.

El resultado es la cadena completa:

git push → GitHub Actions (lint + tests + smoke) → Streamlit Cloud redespliega → app pública actualizada

Un detalle de presentación: el tema

Streamlit permite versionar el aspecto de la app en .streamlit/config.toml, así que el tema viaja con el repo y no depende de la configuración de quien despliega:

[theme]
base = "light"
primaryColor = "#2563EB"
backgroundColor = "#FFFFFF"
secondaryBackgroundColor = "#F1F5F9"
textColor = "#0F172A"

[server]
headless = true

Lo que me llevo

Separa la lógica de datos de la UI. Es una regla de una línea que marca la diferencia entre un proyecto testeable y uno que no lo es.
Prueba los estados vacíos. Todo filtro que el usuario puede vaciar es un NaN o un crash esperando a ocurrir.
Añade un smoke test al CI. Los tests verifican que tu código es correcto; el smoke test verifica que tu aplicación existe.
Elige datos sin dependencias de red cuando puedas. Un CI que depende de una API de terceros es un CI que falla por razones que no son tu culpa y que no puedes arreglar.
Automatiza el despliegue desde el día uno. Configurarlo al principio cuesta 10 minutos; hacerlo al final, con la fecha de entrega encima, cuesta bastante más.

El código completo está en el repositorio, con licencia MIT — clónalo, despliégalo, rómpelo.

📦 Repositorio: https://github.com/JhonyVargas/global-insights-dashboard
🚀 Demo en vivo: https://global-insights-dashboard.streamlit.app

Cómo conversar con tu base de datos usando IA: un generador de SQL a partir de lenguaje natural

JhonyVargas — Sat, 04 Jul 2026 21:12:35 +0000

Artículo técnico — Unidad 3, Base de Datos II

Introducción

Una de las barreras más comunes entre las personas de negocio y sus datos es
el propio SQL: saber que existe la información no sirve de mucho si hay que
escribir un JOIN para llegar a ella. En los últimos años, los modelos de
lenguaje (LLMs) han empezado a cerrar esa brecha con la tarea conocida como
Text-to-SQL: el usuario escribe una pregunta en lenguaje natural y el
modelo genera la consulta SQL correspondiente.

En este artículo muestro una implementación pequeña pero completa de este
patrón, usando un modelo público de Hugging Face, una base de datos SQLite de
ejemplo y una capa de validación que evita que la IA ejecute algo peligroso.
El código completo está disponible en el repositorio público enlazado al
final.

Arquitectura

pregunta (ingles)
   -> modelo T5 afinado en WikiSQL (Hugging Face)
   -> SQL "crudo" generado por el modelo
   -> adaptacion (nombre de tabla real + comillas en valores) y validacion (solo SELECT)
   -> ejecucion en modo solo-lectura sobre SQLite
   -> resultado tabular

La base de datos de ejemplo simula las ventas de una tienda de tecnología,
con una tabla ventas que incluye producto, categoría, precio, cantidad,
ciudad, cliente y fecha:

CREATE TABLE ventas (
    id INTEGER PRIMARY KEY,
    product TEXT NOT NULL,
    category TEXT NOT NULL,
    price REAL NOT NULL,
    quantity INTEGER NOT NULL,
    city TEXT NOT NULL,
    customer TEXT NOT NULL,
    sale_date TEXT NOT NULL
)

El modelo: Hugging Face + T5 afinado en WikiSQL

Para generar SQL usé mrm8488/t5-base-finetuned-wikiSQL, un modelo T5
disponible en Hugging Face y entrenado sobre el dataset WikiSQL. Se usa así:

from transformers import T5ForConditionalGeneration, T5Tokenizer

MODEL_NAME = "mrm8488/t5-base-finetuned-wikiSQL"

class TextToSQL:
    def __init__(self, model_name: str = MODEL_NAME):
        self.tokenizer = T5Tokenizer.from_pretrained(model_name)
        self.model = T5ForConditionalGeneration.from_pretrained(model_name)

    def generate(self, question: str) -> str:
        prompt = f"translate English to SQL: {question} </s>"
        features = self.tokenizer([prompt], return_tensors="pt")
        output_ids = self.model.generate(
            input_ids=features["input_ids"],
            attention_mask=features["attention_mask"],
            max_length=128,
        )
        return self.tokenizer.decode(output_ids[0], skip_special_tokens=True)

Para la pregunta how many products were sold in Madrid, el modelo entrega
algo como:

SELECT COUNT(product) FROM table WHERE city = Madrid

Dos detalles a resolver antes de poder ejecutar esto: la tabla genérica
table (así es como WikiSQL nombra sus tablas de entrenamiento) y el valor
Madrid sin comillas.

La parte que casi nadie muestra: el modelo no conoce tu esquema

Al probar el modelo con preguntas reales aparecieron tres problemas que no se
ven en los ejemplos "de juguete" que suelen circular en tutoriales:

A veces omite los paréntesis de las funciones de agregación: SELECT COUNT Product FROM table WHERE City = Madrid en vez de SELECT COUNT(Product) FROM table WHERE City = 'Madrid'.
El modelo no sabe que nuestra tabla se llama ventas ni que sus columnas son product, category, price, quantity, city, customer y sale_date. WikiSQL entrena con miles de tablas distintas, así que el modelo "inventa" un nombre de columna plausible a partir de las palabras de la pregunta (city a veces sale como City, otras como Location).
No siempre respeta la capitalización real de los datos: generó City = barcelona (minúscula) cuando en la base de datos el valor guardado es Barcelona. Si se ejecuta tal cual, la consulta no falla, pero devuelve 0 filas silenciosamente — el peor tipo de error porque parece que funcionó.

Es tentador tomar el string que devuelve el modelo y pasarlo directo a
cursor.execute(). Es también la forma más rápida de abrir una puerta a
inyección SQL, a que el modelo "alucine" un DROP TABLE, o a que un falso
negativo silencioso pase como resultado correcto. Por eso textsql/sanitize.py
hace cuatro cosas antes de que cualquier SQL toque la base de datos:

1. Reparar los paréntesis faltantes en las funciones de agregación:

_AGG_NO_PARENS = re.compile(
    r"\b(COUNT|SUM|AVG|MIN|MAX)\s+(?!\()([A-Za-z_]\w*)(?:\s+[A-Za-z_]\w*)*\s+FROM",
    re.IGNORECASE,
)

def _fix_missing_parens(sql: str) -> str:
    return _AGG_NO_PARENS.sub(lambda m: f"{m.group(1)}({m.group(2)}) FROM", sql)

2. Renombrar la tabla genérica y poner comillas en los valores de
texto sueltos (igual que en la primera versión).

3. Normalizar columnas con un diccionario de sinónimos, ya que el modelo
no ve el esquema real:

COLUMN_SYNONYMS = {
    "product": "product", "item": "product",
    "category": "category", "type": "category",
    "price": "price", "cost": "price", "amount": "price",
    "quantity": "quantity", "qty": "quantity",
    "city": "city", "location": "city", "town": "city",
    "customer": "customer", "client": "customer", "buyer": "customer",
    "date": "sale_date", "sale": "*", "sales": "*",
}

Con esto, COUNT Sale (una columna que no existe) termina traduciéndose a
COUNT(*), que es exactamente lo que alguien quiere decir con "cuántas
ventas hubo".

4. Comparar sin distinguir mayúsculas, para no devolver falsos negativos
silenciosos:

def _case_insensitive_compare(sql: str) -> str:
    return _STRING_EQUALITY.sub(
        lambda m: f"LOWER({m.group(1)}) = LOWER('{m.group(2)}')", sql
    )

Y finalmente, validar que lo único que se ejecute sea un SELECT, sin
comandos encadenados ni palabras clave destructivas:

FORBIDDEN_KEYWORDS = re.compile(
    r"\b(insert|update|delete|drop|alter|attach|detach|pragma|create|replace|vacuum)\b",
    re.IGNORECASE,
)

def validate_select_only(sql: str) -> None:
    if not sql.strip().upper().startswith("SELECT"):
        raise UnsafeQueryError("Solo se permiten consultas SELECT generadas por el modelo.")
    if ";" in sql:
        raise UnsafeQueryError("No se permiten multiples sentencias en una misma consulta.")
    if FORBIDDEN_KEYWORDS.search(sql):
        raise UnsafeQueryError("La consulta generada contiene palabras clave no permitidas.")

Como defensa adicional, la conexión a SQLite se abre en modo solo-lectura
(file:ventas.db?mode=ro), de forma que incluso si algo se filtrara por la
validación, la base de datos no podría modificarse.

De la terminal a una demo web con Streamlit

Con el motor ya funcionando, envolverlo en una interfaz web con Streamlit
toma menos de 30 líneas:

import streamlit as st
from textsql.db import TABLE_NAME, run_query
from textsql.model import TextToSQL
from textsql.sanitize import adapt_sql, validate_select_only

st.title("🗄️ Pregunta a tu base de datos en lenguaje natural")

question = st.text_input("Escribe tu pregunta en ingles")

if st.button("Generar y ejecutar") and question:
    sql = adapt_sql(engine.generate(question), TABLE_NAME)
    st.code(sql, language="sql")
    validate_select_only(sql)
    st.dataframe(run_query(sql))

El resultado es una página donde se escribe, por ejemplo, what is the total price where city is Barcelona, se ve el SQL generado y la tabla de
resultados en tiempo real.

Resultados y limitaciones

Con la tabla ventas de ejemplo (120 filas sintéticas) y la capa de
normalización en su lugar, preguntas como estas se ejecutan correctamente de
principio a fin:

"how many products were sold in city Madrid"
  -> SELECT COUNT(product) FROM ventas WHERE LOWER(city) = LOWER('Madrid')

"how many sale in category Phones"
  -> SELECT COUNT(*) FROM ventas WHERE LOWER(category) = LOWER('Phones')

"what is the customer where product is Smartwatch"
  -> SELECT customer FROM ventas WHERE LOWER(product) = LOWER('Smartwatch')

Aún así, el prototipo tiene límites claros:

Si la pregunta usa una palabra que no está en COLUMN_SYNONYMS, la consulta puede fallar al ejecutarse (se muestra el error en pantalla en vez de arriesgarse a ejecutar algo incorrecto).
Preguntas que requieren varias tablas o subconsultas (WikiSQL solo entrena con una tabla por ejemplo).
Preguntas en español: el modelo fue entrenado en inglés, así que hay que traducir la pregunta antes de enviarla (una extensión natural del proyecto sería añadir un paso de traducción automática).

Estas limitaciones son, en sí mismas, una buena lección: los modelos
Text-to-SQL de hoy son excelentes asistentes para consultas exploratorias
sencillas, pero todavía necesitan una capa de validación humana o automática
antes de confiar en ellos para producción.

Conclusión

Combinar una base de datos SQL con un modelo de IA no requiere infraestructura
compleja: con un modelo público de Hugging Face, unas 100 líneas de Python y
una capa de sanitización cuidadosa, es posible construir un prototipo
funcional de "conversación con la base de datos" en una tarde. El reto
interesante no está en generar el SQL, sino en decidir cuánto confiar en él
antes de ejecutarlo.

Referencias

Cómo comunicarse con cualquier base de datos mediante IA: crea tu propio extractor de datos con consultas SQL.
Texto a SQL — Hugging Face.
Cómo crear un generador de consultas SQL a partir de texto con Streamlit y Hugging Face (Medium), por Kuhelidey.
Código completo: https://github.com/JhonyVargas/text-to-sql-ia