Dash: Un Agente de Datos Autoaprendiz con Seis Capas de Contexto

Introducción

En la era de los modelos de lenguaje grandes, generar SQL preciso a partir de consultas en lenguaje natural sigue siendo un reto. Dash (repositorio: https://github.com/agno-agi/dash) aborda este problema combinando búsqueda híbrida, una base de conocimiento rica y un bucle de aprendizaje ligero. Es una biblioteca Python de código abierto que puedes insertar en un proyecto o ejecutar como un servicio independiente.

¿Por qué Dash?

• Respuestas Fundamentadas en Contexto: 6 capas de contexto (esquema, reglas de negocio, patrones de consulta, documentos institucionales, aprendizajes, esquema en tiempo de ejecución) significan que cada respuesta está informada por datos reales.
• Auto-Optimización sin Reentrenamiento: La máquina de aprendizaje registra patrones de error y correcciones al instante, haciendo al agente más inteligente tras cada consulta.
• Aprendizaje Continuo Sin Costo: La afinación amigable con la CPU se sustituye por un bucle ligero sin requerir GPU.
• Código Abierto y Extensible: Más de 100 estrellas en GitHub, licencia Apache‑2.0 y una estructura de carpetas clara para añadir conocimiento.

Arquitectura Central

flowchart TD
  A[User Question] --> B[Retrieve Knowledge + Learnings]
  B --> C[Reason About Intent]
  C --> D[Generate Grounded SQL]
  D --> E[Execute & Interpret]
  E -->|Success| F[Return Insight]
  E -->|Error| G[Diagnose → Fix → Save Learning]
  G --> C

Las Seis Capas de Contexto

1. Uso de Tablas – Archivos JSON que describen esquemas, columnas y relaciones.
2. Anotaciones Humanas – Métricas de negocio, definiciones y reglas.
3. Patrones de Consulta – Fragmentos SQL probados almacenados en archivos .sql.
4. Conocimiento Institucional – Documentos externos o wikis (opcional).
5. Aprendizajes – Correcciones generadas por máquina.
6. Contexto en Tiempo de Ejecución – Introspección de esquema en vivo vía la herramienta introspect_schema.

Inicio Rápido

# Clonar el repositorio
git clone https://github.com/agno-agi/dash && cd dash

# Configurar tu clave de OpenAI
cp example.env .env
# Edita .env para agregar OPENAI_API_KEY

# Construir y arrancar el servicio
docker compose up -d --build

# Cargar datos y conocimiento de muestra
docker exec -it dash-api python -m dash.scripts.load_data
docker exec -it dash-api python -m dash.scripts.load_knowledge

Ahora tu API está disponible en http://localhost:8000/docs.

Usar la Interfaz Web

1. Abre https://os.agno.com y accede.
2. Añade un Servidor Online → Local → http://localhost:8000.
3. Haz clic en Conectar.
4. Haz preguntas como:
5. ¿Quién ganó más Campeonatos Mundiales de F1?
6. ¿Cuántas carreras ha ganado Lewis Hamilton?
7. El agente utiliza automáticamente las seis capas de contexto para proporcionar una respuesta significativa.

Flujo de Consulta de Muestra

Usuario: ¿Cuál fue el ingreso total en el último trimestre?

1. Dash localiza el esquema de la tabla `orders` y las reglas de negocio.
2. Selecciona un patrón de consulta guardado que calcula ingresos.
3. Genera SQL con filtrado adecuado (excluye pedidos reembolsados).
4. Ejecuta contra la base de datos.
5. Devuelve un resumen legible por humanos.

Explicación del Bucle de Auto‑Aprendizaje

1. Éxito en la Ejecución – Se devuelve la información.
2. Fallo en la Ejecución – Dash diagnostica el error (por ejemplo, tipo de dato incorrecto), aplica la corrección y la almacena en learnings.
3. La próxima vez que se ejecute una consulta similar, la corrección se aplicará automáticamente.
4. Como este bucle corre en segundo plano, no se necesita entrenamiento de ingeniería adicional.

Añadir o Actualizar Conocimiento

Dash espera una carpeta knowledge/ bien estructurada:

knowledge/
├── tables/          # Metadatos JSON de tablas
├── queries/         # Patrones SQL
└── business/        # Reglas y métricas de negocio

Ejecuta:

python -m dash.scripts.load_knowledge
# Para un inicio limpio
python -m dash.scripts.load_knowledge --recreate

Ejemplo: Metadatos de Tabla

{
  "table_name": "orders",
  "table_description": "Customer orders with denormalized line items",
  "use_cases": ["Revenue reporting", "Customer analytics"],
  "data_quality_notes": ["created_at is UTC", "status values: pending, completed, refunded", "amount stored in cents"]
}

Ejemplo: Patrón de Consulta

-- <query name>monthly_revenue
-- <query description>
-- Monthly revenue calculation.
-- Converts cents to dollars.
-- Excludes refunded orders.
-- </query description>
SELECT
  DATE_TRUNC('month', created_at) AS month,
  SUM(amount) / 100.0 AS revenue_dollars
FROM orders
WHERE status = 'completed'
GROUP BY 1
ORDER BY 1 DESC;

Despliegue en Railway

# Iniciar sesión en Railway
railway login

# Iniciar los servicios requeridos
./scripts/railway_up.sh

# Cargar datos/conocimiento
railway run python -m dash.scripts.load_data
railway run python -m dash.scripts.load_knowledge

# Revisar logs
railway logs --service dash

El panel de Railway facilita visualizar métricas, actualizar variables de entorno y redeployar tras cambios de código.

Buenas Prácticas

• Mantener el Conocimiento Actualizado: Revisar y refinar regularmente los metadatos de tablas y los patrones de consulta.
• Monitorear Aprendizajes: Inspecciona el directorio learnings para ver qué correcciones está aplicando el agente.
• Asegurar la API: Añade capas de autenticación para despliegues en producción.
• Aprovechar la API EXA (opcional) para contexto adicional de búsqueda web.

Conclusión

Dash demuestra cómo un bucle de auto‑aprendizaje minimalista combinado con conocimiento estructurado puede mejorar drásticamente los flujos de trabajo de lenguaje natural a SQL. Como proyecto de código abierto bajo Apache‑2.0, invita a contribuciones de la comunidad—ya sea añadiendo nuevos patrones de consulta o expandiendo el motor de aprendizajes. Si buscas un asistente AI ligero que siga aprendiendo sin reentrenamiento, Dash es un punto de partida convincente.

¡Feliz consulta! 🚀