ESTÁNDAR ABIERTO HAIC · V1

Construye un taller que
otros puedan continuar.

Antes de aportar código, prepara una experiencia reproducible: datos con intención, un modelo auditable y una demostración que invite a la comunidad a participar.

Revisar requisitos →Ver estructura

01 / REPOSITORIO

Una estructura compartida reduce la fricción.

Todos los talleres parten del mismo mapa. Así, los participantes encuentran rápidamente los datos, el pipeline, el modelo y la API.

haic-project-template

├── data/                    # Persistencia local · ignorado en Git
├── models/                  # Modelos .joblib/.onnx · ignorado en Git
├── raw_data/
│   ├── fase_1/              # Histórico ~70% · público
│   └── fase_2/              # Live drop ~30% · privado
├── src/
│   ├── utils.py             # Fórmulas y helpers
│   ├── pipeline.py          # Ingesta ETL / ELT
│   ├── train.py             # Entrenamiento y evaluación
│   └── app.py               # API de inferencia FastAPI
├── pyproject.toml           # Dependencias con uv
├── README.md                # Guía pública
└── SHOW_AND_TELL_GUIDE.md   # Guion privado del expositor

DATA

Separa datos históricos, datos en vivo y persistencia local.

MODEL

Mantén los artefactos entrenados fuera del repositorio público.

SOURCE

Divide responsabilidades en scripts pequeños y comprensibles.

02 / CONTROL DE VERSIONES

La rama pública enseña; la solución privada respalda.

RAMA PÚBLICA

main

Plantillas, importaciones y comentarios estructurados. La lógica permanece por construir.

✓ Código inicial guiado
✓ Fase 1 de los datos
✓ README público

git branch

REFERENCIA PRIVADA

desarrollo-completo

Solución programada y modelo entrenado para preparar y respaldar la demostración.

✓ Implementación completa
✓ Modelo validado
✓ Guion del expositor

.gitignoreLo que no debe publicarse

data/
models/
raw_data/fase_2/
SHOW_AND_TELL_GUIDE.md

La Fase 2 se libera durante el taller para producir el momento de descubrimiento y simular datos que llegan en vivo.

03 / CÓDIGO

Cuatro módulos, una historia completa.

Cada archivo cumple una responsabilidad y prepara el siguiente paso del flujo.

01UTILIDADES

src/utils.py

Haz visible el razonamiento

Declara firmas y docstrings claros. Las fórmulas matemáticas deben quedar señaladas para que los participantes puedan implementarlas manualmente.

02PIPELINE

src/pipeline.py

De datos crudos a ML Ready

Usa DuckDB para persistencia y Pandas para transformar. Implementa capas Bronze, Silver y Gold, cargas incrementales sin duplicados y la auditoría processed_at.

03MODELO

src/train.py

Entrena de forma reproducible

Filtra targets nulos, divide Train/Test de manera estratificada y atiende el desbalance. Serializa el resultado con joblib y compresión.

04INFERENCIA

src/app.py

Convierte el modelo en experiencia

Sirve el modelo con FastAPI, cárgalo una sola vez mediante lifespan y ofrece inferencia batch y live drop con límites de respuesta.

REGLA DE AUDITORÍA

`processed_at` conecta el pipeline con el momento en vivo.

La capa Gold debe registrar la hora actual para que la API consulte exactamente los datos procesados durante los últimos cinco minutos.

04 / SHOW & TELL

No presentes diapositivas.
Presenta un sistema que reacciona.

ESTADO INICIAL

Levanta el entorno

Inicia la API y el orquestador. Comprueba que la consulta está vacía antes de procesar nuevos datos.

LIVE DROP

Libera la Fase 2

Ejecuta la ingesta y observa el DAG interactivo mientras el pipeline transforma los datos.

INFERENCIA

Haz visible la reacción

Consulta Swagger y demuestra cómo el sistema encuentra, procesa y etiqueta los registros recientes.

El guion completo vive en SHOW_AND_TELL_GUIDE.md y permanece fuera de Git para no anticipar la experiencia.