01 — Qué es AURA JAC

AURA JAC es un asistente conversacional de inteligencia analítica diseñado para la empresa de buses interurbanos JAC (Jugos y Alimentos de Concepción, operador de transporte de pasajeros en Chile). Permite a ejecutivos y analistas realizar preguntas sobre ventas de boletos en lenguaje natural en español y obtener respuestas analíticas con datos, visualizaciones y explicaciones en texto.

Qué resuelve

Capacidades principales

Versión actual

Datos reales anonimizados: enero 2023 – junio 2024.

02 — Stack Tecnológico

Dependencias (requirements.txt)

openai>=1.0.0           # Cliente DeepSeek (compatible con OpenAI API)
chromadb>=1.5.0         # Embeddings MiniLM para retrieval híbrido
rank-bm25>=0.2.2        # Retrieval léxico (BM25)
sqlglot>=25.0.0         # Validación/parseo de SQL
numpy>=1.26.0           # Álgebra para fusión de retrieval
pandas>=2.2.0
plotly>=5.24.0
streamlit>=1.40.0       # Interfaz web
python-dotenv>=1.0.1    # Variables de entorno

03 — Arquitectura General

Diagrama de alto nivel

                        ┌─────────────────────────┐
                        │      Usuario humano      │
                        │  (ejecutivo / analista)  │
                        └────────────┬────────────┘
                                     │
                    ┌────────────────▼────────────────┐
                    │     Interfaz Streamlit (app.py)  │
                    │  · Chat web con historial        │
                    │  · Detección de intención (LLM)  │
                    │  · Gráficos Plotly               │
                    └────────────────┬────────────────┘
                                     │
                    ┌────────────────▼────────────────┐
                    │   Asistente (assistant.py)       │
                    │  · Analiza intención (CONV/DATA) │
                    │  · Traduce a formato Vanna       │
                    │  · Genera explicación NL          │
                    └────────────────┬────────────────┘
                                     │
                    ┌────────────────▼────────────────┐
                    │   Motor GenBI (engine.py)        │
                    │  · Orquesta todo el pipeline     │
                    │  · Self-correction               │
                    │  · Voting por ejecución          │
                    └────────────────┬────────────────┘
                                     │
          ┌──────────────────────────┼──────────────────────────┐
          │                          │                          │
  ┌───────▼────────┐  ┌─────────────▼─────────────┐  ┌────────▼────────┐
  │ Schema Linking  │  │   Retrieval Híbrido        │  │   Knowledge     │
  │ (determinista)  │  │   (embeddings + BM25)      │  │   (DDL + catálogo│
  │                 │  │                             │  │    de valores)   │
  └───────┬────────┘  └─────────────┬─────────────┘  └────────┬────────┘
          │                          │                          │
          └──────────────────────────┼──────────────────────────┘
                                     │
                    ┌────────────────▼────────────────┐
                    │   Generación (generation.py)     │
                    │  · N candidatos (1 greedy + N-1  │
                    │    muestreados a T=0.6)          │
                    │  · Batch paralelo                │
                    └────────────────┬────────────────┘
                                     │
                    ┌────────────────▼────────────────┐
                    │   Validación (validation.py)     │
                    │  · sqlglot (AST check)           │
                    │  · Solo SELECT, 1 sentencia      │
                    │  · Auto-repair de STRFTIME       │
                    └────────────────┬────────────────┘
                                     │
                    ┌────────────────▼────────────────┐
                    │   Ejecución (sql_exec.py)        │
                    │  · Read-only mode=ro             │
                    │  · Timeout 25s                   │
                    │  · Execution feedback loop       │
                    └────────────────┬────────────────┘
                                     │
                    ┌────────────────▼────────────────┐
                    │   Voting (engine.py)             │
                    │  · Firma por result-set          │
                    │  · Majority voting ponderado     │
                    │  · Desempata por SQL más simple  │
                    └────────────────┬────────────────┘
                                     │
                    ┌────────────────▼────────────────┐
                    │   Respuesta                      │
                    │  · SQL + resultado + traza       │
                    │  · Explicación NL + gráfico      │
                    └─────────────────────────────────┘
    

Flujo de datos completo

1. El usuario escribe una pregunta en el chat.
2. Detección de intención (analizar_pregunta en app.py): un LLM clasifica si es conversacional (CONV) o de datos (DATA). Si es conversacional, responde directamente sin ir a la base de datos.
3. Si es DATA, reescribe la pregunta como autónoma incorporando contexto de la conversación previa.
4. Schema linking (schema_linking.py): identifica qué columnas, ciudades y valores relevantes menciona la pregunta.
5. Retrieval híbrido (retrieval.py): recupera ejemplos few-shot y reglas de negocio relevantes usando embeddings + BM25 con RRF.
6. Generación de candidatos (generation.py): construye prompt completo y genera N candidatos SQL.
7. Validación estática (validation.py): cada candidato se valida con sqlglot.
8. Ejecución read-only (sql_exec.py): cada candidato se ejecuta contra SQLite en modo solo lectura.
9. Execution feedback (engine.py): si falla, se reintentа pasando el error al LLM (hasta 2 rondas).
10. Voting (engine.py): se agrupan candidatos por firma de result-set. Gana la firma con más votos.
11. Explicación NL (assistant.py): el LLM genera 1-2 oraciones explicando el resultado.
12. Visualización (app.py): se muestra tabla humanizada y gráfico de barras con Plotly.

04 — Primeros Pasos — Instalación

Requisitos previos

• Python 3.12+ (recomendado)
• pip (gestor de paquetes)
• Una API key de DeepSeek (el sistema usa DeepSeek v4 como LLM)

Instalación local

# 1. Clonar el repositorio
git clone <url-del-repositorio>
cd aura-genbi

# 2. Crear entorno virtual (recomendado)
python -m venv .venv
source .venv/bin/activate   # Linux/Mac
# .venv\Scripts\activate    # Windows

# 3. Instalar dependencias
pip install -r requirements.txt

# 4. Configurar variables de entorno
cp .env.example .env
# Editar .env y agregar tu DEEPSEEK_API_KEY

# 5. Generar datos de ejemplo (opcional, para pruebas)
python generate_data.py

# 6. Cargar datos reales (si tienes los CSVs anonimizados de JAC)
python load_real_data.py

# 7. Lanzar la interfaz web
streamlit run app.py
# Se abre en http://localhost:8501

Usando Make

El proyecto incluye un Makefile con atajos:

make install          # pip install -r requirements.txt
make app              # streamlit run app.py
make test             # python tests/test_comparator.py
make cli Q='¿Cuánto se vendió en 2024?'
make eval-heldout     # Evaluación held-out (45 preguntas)
make eval-robustness  # Evaluación robustez (coloquial/typos)
make eval-hard        # Evaluación hard (CTE/ventanas)
make ablations        # Estudio de ablación
make showcase         # Genera reports/MODEL_SHOWCASE.md

05 — Variables de Entorno

El archivo .env (nunca commitear) controla todo el comportamiento del sistema.

Archivo .env.example

# DeepSeek API (OBLIGATORIO)
DEEPSEEK_API_KEY=tu_api_key_aqui
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1

# Modelos
DEEPSEEK_MODEL=deepseek-v4-pro          # Modelo principal (generación SQL)
DEEPSEEK_MODEL_FLASH=deepseek-v4-flash  # Modelo auxiliar (barato, tareas simples)

# Base de datos
SQLITE_PATH=data/base_jac_real.db       # Ruta al archivo SQLite
CHROMA_PATH=./chroma                    # Directorio de ChromaDB (embeddings)

# Motor GenBI
GENBI_INDEX_PATH=./.genbi_index         # Índice de recuperación persistente

Tabla de variables

06 — Uso de la Interfaz Web (Streamlit)

Acceso

streamlit run app.py
# Abre http://localhost:8501 en tu navegador

Elementos de la interfaz

Header

• Muestra el logo de AURA JAC
• Indica el período de datos: "Ene 2023 – Jun 2024"
• Badge de versión: v2.0

Barra de KPIs

En la parte superior se muestran 5 indicadores clave:

• Ingresos totales (en CLP, formato abreviado)
• Boletos vendidos (count total)
• Pasajeros únicos (count distinct)
• Rutas activas (count distinct)
• Ticket promedio (promedio de VALOR)

Chat

• Pantalla vacía: muestra sugerencias predefinidas clickeables
• Entrada de texto: campo para escribir preguntas en español
• Botón "Enviar →": envía la pregunta
• Historial: conversación completa

Tipos de interacción

Preguntas de datos

El sistema genera SQL, ejecuta, y muestra:

1. Tabla de resultados con columnas humanizadas
2. Gráfico de barras automático (si hay ≥2 filas con columna numérica + textual)
3. Explicación en texto del resultado clave

Preguntas conversacionales

El sistema responde directamente sin SQL:

• "¡Gracias!" → "¡De nada! ¿En qué te puedo ayudar?"
• "¿Qué puedes hacer?" → "Puedo consultarte sobre ventas, rutas, canales..."

Sugerencias predefinidas

Humanización de resultados

07 — Uso por Línea de Comandos (CLI)

Pregunta única

python ask.py "¿Cuál fue la ruta con más ingresos?"

Salida típica:

── SQL ──────────────────────────────────────────
SELECT ORIGEN_DESTINO, SUM(VALOR) AS ingresos_totales
FROM ventas GROUP BY ORIGEN_DESTINO ORDER BY ingresos_totales DESC LIMIT 1

── Resultado ────────────────────────────────────
Ruta | Ingresos
Temuco → Concepción | $285,057,050

── AURA ─────────────────────────────────────────
La ruta Temuco → Concepción generó los mayores ingresos con un total de $285 millones.

[diag] candidatos=3 votos=3 filas=1 t=4.2s

Modo interactivo (REPL)

python ask.py
# Se inicia un REPL donde puedes escribir preguntas
# Escribe "salir", "exit", "quit" o presiona Ctrl-D para terminar

Opciones de CLI

python ask.py --sql-only "¿Cuántos boletos hay?"  # Solo imprime el SQL generado
python ask.py --candidates 5 "Pregunta aquí"       # Usa 5 candidatos (default: 3)

08 — Uso Programático (API Python)

from genbi import Engine, EngineConfig
from genbi.assistant import Assistant

# Crear el motor con configuración personalizada
cfg = EngineConfig(n_candidates=5, use_voting=True)
eng = Engine(cfg)

# Pregunta directa
ans = eng.ask("¿Cuál fue la ruta con más ingresos contando ida y vuelta?")

# Resultados
print(ans.sql)            # SQL final generado
print(ans.result.rows)    # Filas del resultado
print(ans.result.columns) # Nombres de columnas
print(ans.n_votes)        # Votos que ganó
print(ans.trace)          # Traza de diagnóstico
print(ans.elapsed_s)      # Tiempo total en segundos
print(ans.candidates)     # Todos los candidatos evaluados

# Con asistente (incluye explicación NL)
asst = Assistant(eng)
ans = asst.ask("Top 5 rutas con más boletos")
df = DataFrame(ans.result.rows, columns=ans.result.columns)
explanation = asst.explain("Top 5 rutas con más boletos", df, [])
print(explanation)

Objeto Answer

09 — Motor GenBI — Explicación Detallada

Estructura del paquete genbi/

config.py — Hiperparámetros

llm.py — Cliente LLM

• Caché en disco: cada respuesta se guarda con hash SHA-256 de los inputs. Re-ejecutar la misma pregunta no cuesta tokens.
• Reintentos con backoff exponencial: hasta 5 reintentos con espera creciente.
• Batch paralelo: los N candidatos se generan en paralelo usando ThreadPoolExecutor.
• Contabilidad de tokens: rastrea llamadas, prompt tokens, completion tokens y cache hits.

knowledge.py — Capa de Conocimiento

Tres fuentes de grounding:

1. Esquema vivo: introspección directa de la tabla ventas vía PRAGMA table_info. Siempre sincronizado con los datos reales.
2. Catálogo de valores: valores distintos de columnas categóricas, códigos de rutas, rango de fechas, meses disponibles.
3. Diccionario de negocio (diccionario_jac.py): DDL, reglas de negocio documentadas y 118+ pares pregunta→SQL validados.

retrieval.py — Retrieval Híbrido

Combinación de dos señales:

• Dense (embeddings MiniLM): captura similitud semántica (ej: "ingresos" ≈ "recaudación")
• Lexical (BM25): captura nombres exactos de rutas, canales, subcanales

Fusión con Reciprocal Rank Fusion (RRF): combina los rankings de ambas señales de forma robusta y sin parámetros.

schema_linking.py — Grounding Determinista

Mapeo keyword→columna que evita los errores más comunes:

Además detecta ciudades y mapea a códigos (ej: "Temuco" → "tmco"), muestra rutas candidatas y recuerda convenciones de fechas.

validation.py — Validación Estática

• Verifica que sea solo SELECT o WITH...SELECT
• Rechaza DML/DDL (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, etc.)
• Rechaza múltiples sentencias
• Verifica tablas conocidas (ventas, kpis_mensuales, kpis_rutas, kpis_canales)
• Auto-repair: reescribe STRFTIME sobre enteros por la versión correcta

generation.py — Construcción de Prompts

El prompt del sistema instruye al LLM para:

• Generar SOLO SQL (sin explicaciones, sin markdown)
• Usar solo columnas y valores del catálogo
• Respetar la convención de fechas enteras (SUBSTR, no STRFTIME directo)
• Mapear métricas correctamente (ventas=SUM(VALOR), boletos=COUNT(*), ticket=AVG(VALOR))

engine.py — Orquestador

para cada candidato:
    1. validar estáticamente (sqlglot)
    2. auto-reparar errores conocidos
    3. ejecutar read-only (con timeout)
    4. si falla o vacío → execution feedback (hasta 2 rondas):
        - pasar error al LLM
        - generar SQL corregido
        - re-validar
        - re-ejecutar
    5. si devolvió datos → candidato exitoso

voting:
    - agrupar candidatos exitosos por firma del result-set
    - ganador = firma con más votos (ponderados)
    - desempate: SQL más simple
    - (opcional) result_check con LLM si hay empate

retornar Answer con SQL, resultado, traza y diagnóstico

sql_exec.py — Ejecución y Comparación

• Ejecución: conexión SQLite en URI file:path?mode=ro (garantiza solo lectura a nivel de SQLite).
• Timeout: usa threading con timeout configurable.
• Comparación de result-sets: implementa Execution Accuracy estilo Spider/BIRD:
  • Robusto a orden de filas y columnas
  • Acepta columnas auxiliares extra
  • Tolerancia a redondeo (±0.5 CLP o ±0.1%)
  • Insensible a formato de etiquetas temporales
  • Verifica enlace de filas (no acepta valores intercambiados)

10 — Base de Datos y Esquema

Tabla principal: ventas

CREATE TABLE ventas (
    NRO_BOLETO                      INTEGER,  -- ID único del boleto/transacción
    TIPO_DOCUMENTO_PASAJERO         TEXT,     -- Tipo de documento (ej: 'RUT')
    DOCUMENTO_PASAJERO_ANONIMIZADO  INTEGER,  -- Documento anonimizado (PII protegida)
    LINEA                           INTEGER,  -- Línea de servicio (5, 9)
    FECHA_COMPRA                    INTEGER,  -- Fecha compra, YYYYMMDD (ej: 20230122)
    HORA_COMPRA                     INTEGER,  -- Hora compra, HHMM (ej: 2033)
    VALOR                           REAL,     -- Monto del boleto en CLP
    ORIGEN_DESTINO                  TEXT,     -- Trayecto: 'codigoOrigen-codigoDestino'
    FECHA_SALIDA_SERVICIO           INTEGER,  -- Fecha salida, YYYYMMDD
    HORA_SALIDA_SERVICIO            INTEGER,  -- Hora salida, HHMM
    TIPO_ASIENTO                    TEXT,     -- Categoría de asiento
    CANAL_VENTA                     TEXT,     -- 'Presencial' o 'Internet'
    SUBCANAL_VENTA                  TEXT      -- Subcanal específico
);

Convenciones de fechas

• FECHA_COMPRA y FECHA_SALIDA_SERVICIO son enteros YYYYMMDD
• Para extraer partes: SUBSTR(CAST(FECHA_COMPRA AS TEXT), 1, 4) → año
• NUNCA usar STRFTIME() directamente sobre el entero
• Rango de datos: 20230101 – 20240630
• Meses con datos: ene 2023, may 2023, jun 2023, oct 2023, nov 2023, ene 2024, may 2024, jun 2024

Tablas auxiliares (pre-calculadas)

Códigos de ciudad

Formato de rutas

Las rutas se almacenan como ORIGEN_DESTINO con formato codigoOrigen-codigoDestino en minúsculas:

• pcon-tmco = Pucón → Temuco
• tmco-conc = Temuco → Concepción
• stgo-pcon = Santiago → Pucón

Corredores bidireccionales

Cuando el usuario pide datos de "ida y vuelta", hay que normalizar los dos sentidos:

-- Normalización del corredor (alfabéticamente primero el menor)
CASE
  WHEN SUBSTR(ORIGEN_DESTINO,1,INSTR(ORIGEN_DESTINO,'-')-1)
       < SUBSTR(ORIGEN_DESTINO,INSTR(ORIGEN_DESTINO,'-')+1)
  THEN ORIGEN_DESTINO
  ELSE SUBSTR(ORIGEN_DESTINO,INSTR(ORIGEN_DESTINO,'-')+1)
       ||'-'||SUBSTR(ORIGEN_DESTINO,1,INSTR(ORIGEN_DESTINO,'-')-1)
END AS corredor

O más simple: WHERE ORIGEN_DESTINO IN ('tmco-conc', 'conc-tmco')

11 — Diccionario de Negocio JAC

El archivo diccionario_jac.py contiene toda la información de negocio que el motor inyecta al LLM.

1. DDL

La definición exacta de la tabla ventas (ver sección anterior).

2. Reglas de negocio (DOCUMENTACION)

100+ reglas documentadas incluyendo:

• Cobertura temporal (meses disponibles, rango de fechas)
• Códigos geográficos y trayectos frecuentes
• Convención de corredores ida y vuelta
• Canales y subcanales de venta (valores exactos)
• Tipos de asiento (valores exactos y agrupaciones)
• Líneas de servicio (5, 9)
• Métricas financieras (SUM, COUNT, AVG)
• Convención de fechas enteras
• Seguridad (solo lectura)

3. Ejemplos validados (EJEMPLOS)

118+ pares pregunta→SQL validados sobre datos reales, cubriendo: rankings, análisis temporales, corredores bidireccionales, canales, tipos de asiento, pasajeros, geografía, horarios, distribución de precios, KPIs, líneas de servicio, concentración (Pareto), preguntas combinadas y window functions.

Cómo extender el diccionario

# En diccionario_jac.py, agregar al final de la lista EJEMPLOS:
{
    "question": "Tu nueva pregunta en español",
    "sql": "SELECT ... FROM ventas WHERE ...".strip(),
},

12 — Pipeline de Generación de SQL

Ejemplo completo: "¿Cuál fue la ruta con más ingresos contando ida y vuelta?"

13 — Sistema de Evaluación

Métrica: Execution Accuracy (EX)

Estándar de Spider/BIRD: dos consultas son equivalentes si sus result-sets coinciden. El comparador es robusto a orden de filas/columnas, columnas auxiliares extra, redondeo (±0.5 CLP) y formato de etiquetas temporales.

Benchmarks

Ejecutar evaluación

# Held-out (generalización)
python eval/harness.py \
    --benchmark eval/benchmark_heldout.json \
    --out reports/heldout --label heldout

# Robustez
python eval/harness.py \
    --benchmark eval/benchmark_robustness.json \
    --out reports/robustness --label robustness

# Hard
python eval/harness.py \
    --benchmark eval/benchmark_hard.json \
    --out reports/hard --label hard

# In-domain (default)
python eval/harness.py --out reports/indomain --label indomain

Opciones de evaluación

--candidates N     # Número de candidatos (default: 5)
--workers N        # Workers paralelos (default: 4)
--sample N         # Muestrear N preguntas aleatorias
--no-voting        # Desactivar voting
--no-feedback      # Desactivar execution feedback
--no-linking       # Desactivar schema linking
--no-embeddings    # Solo BM25 (sin embeddings)
--model NAME       # Cambiar el modelo LLM

Estudio de ablación

python eval/ablations.py

Showcase cualitativo

python eval/showcase.py --explain
# Genera reports/MODEL_SHOWCASE.md

Tests del comparador

python tests/test_comparator.py

Batería de 21 casos adversariales que verifican que el comparador acepta variaciones legítimas y rechaza errores reales.

14 — Despliegue con Docker

Dockerfile

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8501
CMD ["sh", "-c", "streamlit run app.py --server.port=8501 --server.address=0.0.0.0"]

docker-compose.yml

services:
  jac-genbi:
    build: .
    container_name: jac-genbi
    ports:
      - "8501:8501"
    env_file:
      - .env
    volumes:
      - ./chroma:/app/chroma     # memoria vectorial persistente
      - ./data:/app/data         # base de datos

Desplegar

# Construir y levantar
docker compose up -d --build

# Ver logs
docker compose logs -f

# Detener
docker compose down

Persistencia

Los volúmenes montados aseguran que:

• chroma/: la memoria vectorial (embeddings) persiste entre reinicios
• data/: la base de datos SQLite persiste entre reinicios
• .genbi_cache/: el caché de respuestas LLM se mantiene (agregar al compose si se necesita)

Producción

15 — Seguridad

Garantías de solo lectura

El sistema tiene tres capas de protección contra escritura:

1. Validación estática (validation.py): rechaza cualquier SQL que no empiece con SELECT o WITH...SELECT.
2. Parsing AST (sqlglot): verifica que la consulta sea un único statement SELECT sobre tablas conocidas.
3. Ejecución SQLite mode=ro: la conexión se abre con file:path?mode=ro, garantía a nivel de SQLite de que no se puede escribir.

Protección de datos personales

• DOCUMENTO_PASAJERO_ANONIMIZADO contiene documentos ya anonimizados
• No se exponen datos personales identificables
• La columna TIPO_DOCUMENTO_PASAJERO solo contiene "RUT" (tipo genérico)

Variables sensibles

• DEEPSEEK_API_KEY nunca se commitea (.env está en .gitignore)
• No se loguean API keys en ningún lado
• El caché LLM usa hashes SHA-256, no almacena prompts completos en metadatos

16 — Cómo Mejorar el Sistema

Mejoras implementadas (v2)

Mejoras pendientes

Guías de extensión

Agregar nuevas preguntas de entrenamiento

1. Agregar la pregunta y SQL validado a diccionario_jac.py → EJEMPLOS
2. Re-ejecutar el benchmark: python eval/harness.py --out reports/after_addition
3. El retrieval híbrido automáticamente incorporará los nuevos ejemplos

Agregar nuevas reglas de negocio

1. Agregar la regla a diccionario_jac.py → DOCUMENTACION
2. La regla se inyectará automáticamente a los prompts relevantes

Cambiar de modelo LLM

1. Si es compatible con OpenAI API: solo cambiar DEEPSEEK_MODEL en .env
2. Si usa otro formato: modificar genbi/llm.py
3. Ajustar max_tokens y temperature en EngineConfig

Escalar a PostgreSQL

1. Modificar genbi/sql_exec.py para usar psycopg2
2. Modificar genbi/knowledge.py para introspeccionar esquema PostgreSQL
3. Cambiar SQLITE_PATH por connection string
4. Ajustar consultas de introspección (PRAGMA → information_schema)

Agregar nuevas métricas

1. En app.py, agregar la columna a COL_DISPLAY
2. Agregar keywords a _CLP_KW si es un monto en CLP
3. En diccionario_jac.py, agregar la definición en DOCUMENTACION

17 — Solución de Problemas

"Falta DEEPSEEK_API_KEY en el archivo .env"

cp .env.example .env
# Editar .env y agregar tu DEEPSEEK_API_KEY

"No pude inicializar el agente"

1. Verificar que .env tenga DEEPSEEK_API_KEY válido
2. Verificar que data/base_jac_real.db exista
3. Revisar logs del error específico

La interfaz no carga / queda en blanco

pip install streamlit
streamlit run app.py --logger.level=debug

El LLM devuelve SQL incorrecto

El sistema aplica execution feedback automáticamente. Si después de 2 intentos sigue fallando, reescribir la pregunta de forma más específica:

• Malo "ventas del corredor"
• Bueno "ingresos del corredor Temuco-Concepción ida y vuelta en 2024"

El gráfico no aparece

Plotly solo genera gráfico si hay ≥2 filas con al menos una columna numérica y una textual. Hacer una pregunta que retorne múltiples filas.

Lentitud en respuestas

1. Reducir n_candidates en EngineConfig (default 3)
2. Usar DEEPSEEK_MODEL_FLASH para generación
3. Verificar conexión a internet (latencia a la API de DeepSeek)

Los datos muestran "0" o vacío

-- Verificar qué meses tienen datos
SELECT DISTINCT SUBSTR(CAST(FECHA_COMPRA AS TEXT),1,6) FROM ventas;

-- Verificar rango de fechas
SELECT MIN(FECHA_COMPRA), MAX(FECHA_COMPRA) FROM ventas;

Error de Docker: "port already in use"

lsof -ti:8501 | xargs kill -9
# O usar otro puerto en docker-compose.yml: "8502:8501"

18 — Glosario

19 — Referencias

Paper del proyecto

• ARQUITECTURA.md — Diseño detallado del sistema
• MEJORAS_TEXT_TO_SQL.md — Catálogo de mejoras con estado de implementación
• reports/EVALUACION_DETALLADA.md — Resultados completos de evaluación
• reports/ablations.md — Estudio de ablación

Investigación académica

• SIRIUS-SQL: Multi-Candidate + Execution Feedback
• Dynamic-SQL: Multi-Path Fusion + Self-Correction
• CHASE-SQL
• TriSQL: Three-Stage Framework
• TAHOE: Hint Bank from Execution Feedback
• Google Cloud Text-to-SQL Techniques
• Text-to-SQL Leaderboard 2026

Métricas de evaluación

• Spider Benchmark: Execution Accuracy estándar para Text-to-SQL
• BIRD Benchmark: Benchmark de evaluación con datos del mundo real

20 — Estructura Completa del Proyecto