13. Guía de onboarding

Plan de estudio de 5 semanas para un nuevo integrante, con orden de lectura, objetivos, ejercicios prácticos y criterios de "ya lo dominas". Ajusta el ritmo a tu experiencia previa: un desarrollador sin ML puede necesitar más tiempo en las semanas 1-2; uno con ML puede acelerar.

Antes de empezar: setup (día 0)

1. Lee LOCAL.md del repo y levanta el entorno: crea el venv, make install, configura .env con DATASET_ROOT, y make download-dataset.
2. Verifica que todo funciona: make test-loader (smoke check) y make summary (conteo por clase).
3. Si algo falla, casi siempre es el .env: get_dataset_root() da un mensaje claro.

Criterio de listo: make test-loader pasa sin errores.

Semana 1 — Panorama y arquitectura

Objetivo: entender qué hace el sistema y cómo está organizado, sin entrar al detalle del código.

Lectura (en orden):

1. Resumen ejecutivo — el qué, el porqué, las 9 clases, los resultados.
2. Mapa del repositorio — la topología, la dualidad src/scripts.
3. Flujo completo del sistema — el recorrido de una imagen de punta a punta.
4. Si no tienes background de ML: hojea el Glosario en paralelo.

Ejercicio práctico:

• Recorre el árbol del repo con la mano en el mapa. Abre 3 archivos de src/ y 3 de scripts/ y clasifícalos como "componente" o "entrypoint".
• Corre make summary y anota la distribución de clases. ¿Cuál es la más y la menos frecuente? Calcula el ratio.

Criterio de dominio: puedes dibujar de memoria el diagrama de las 9 etapas y explicar la diferencia entre train_baselines.py y train.py.

Semana 2 — Datos y preprocesamiento

Objetivo: dominar cómo se preparan y cargan los datos (la capa más crítica).

Lectura:

1. Configuración y rutas — el YAML y config.py.
2. Capa de datos — loader, dataset, splitter, transforms (léela con el código abierto al lado).
3. Fundamentos: Data Augmentation, regularización.

Ejercicio práctico:

• Corre make splits-baseline y abre outputs/splits/seed_42_baseline/split_audit_report.csv. Verifica que la proporción 70/15/15 se cumple por clase.
• Lee compute_minority_classes y calcula a mano qué clases son minoritarias con umbral 4.0 usando los conteos de make summary.
• Abre un run existente y mira augmentation_preview/: compara el grid de una clase minoritaria vs una mayoritaria. ¿Ves la diferencia de agresividad?

Criterio de dominio: puedes explicar por qué saturación/hue están casi en cero, por qué se deduplica por hash, y qué hace el for/else de __getitem__.

Semana 3 — Modelos y entrenamiento

Objetivo: entender cómo se construyen los modelos y cómo funciona el loop.

Lectura:

1. Modelos y registry — el patrón registry, transfer learning en código.
2. Entrenamiento — common.py, el loop de train_baselines.py.
3. Fundamentos: CNN, transfer learning, backprop, optimizadores, cross-entropy.
4. Hiperparámetros.

Ejercicio práctico:

• Entrena un modelo corto: make train-baselines MODELS=shufflenet_v2_x1_0 EPOCHS=3. Observa train_history.csv mientras corre.
• Abre summary.json del run y localiza cada hiperparámetro en el código que lo generó.
• Cambia el LR: make train-baselines MODELS=shufflenet_v2_x1_0 EPOCHS=3 LEARNING_RATE=0.01. Compara la loss. ¿Diverge o mejora?

Criterio de dominio: puedes trazar el camino de un batch desde el DataLoader hasta optimizer.step(), y explicar por qué se guarda best.pth por macro-F1.

Semana 4 — Evaluación e inferencia

Objetivo: interpretar resultados y correr inferencia/explicabilidad.

Lectura:

1. Fundamentos: métricas, matriz de confusión, XAI.
2. Explicabilidad (código).
3. Scripts de soporte: predict.

Ejercicio práctico:

• Abre test_confusion_matrix.csv de un run. Identifica las dos clases que más se confunden entre sí. ¿Tiene sentido agronómico (síntomas parecidos)?
• Corre make explain-lime MODELS=<tu-modelo> y abre un PNG de lime_visual/. ¿LIME y Grad-CAM coinciden en la lesión?
• Corre make explain-errors MODELS=<tu-modelo> y mira un error. ¿En qué se fijó el modelo al equivocarse?
• Predice una imagen: python scripts/pipeline/predict.py --model <m> --image <ruta>.

Criterio de dominio: puedes leer una matriz de confusión, interpretar un panel LIME+Grad-CAM y explicar la métrica explanation_dispersion.

Semana 5 — Decisiones, riesgos y defensa

Objetivo: pasar de "sé cómo funciona" a "puedo defenderlo y mejorarlo".

Lectura:

1. Decisiones técnicas — el porqué de cada elección.
2. ¿Qué pasaría si...? — la sensibilidad del sistema.
3. Riesgos técnicos — limitaciones y fragilidades.
4. Banco de preguntas — auto-evaluación.
5. Guía de defensa.

Ejercicio práctico:

• Responde las 28 preguntas del banco sin mirar las respuestas. Compara.
• Prepara una defensa de 10 minutos siguiendo el guion de la sección 12.8.
• Elige una limitación de riesgos y propón una mejora concreta con su plan de implementación.

Criterio de dominio: puedes justificar cualquier decisión del proyecto contra su alternativa, y responder a una objeción sin inventar datos.

Ruta rápida (para experimentados con ML)

Si ya dominas ML y solo necesitas conocer este proyecto:

Puedes saltarte los fundamentos teóricos (sección 5) y el glosario, y usarlos solo como referencia puntual.

Primeras contribuciones sugeridas (para aprender haciendo)

Ordenadas de menor a mayor dificultad:

1. Fácil: añadir un test unitario de compute_minority_classes o build_weighted_sampler.
2. Fácil: entrenar y explicar un modelo del registry aún no comparado (p.ej. ghostnetv2_100) y documentar sus métricas.
3. Media: añadir un learning rate scheduler opcional a train_baselines.py.
4. Media: implementar dedup perceptual opcional en create_splits.py.
5. Difícil: implementar el loop de entrenamiento de train.py reusando _run_epoch.
6. Difícil: pipeline de exportación a TFLite Int8 + validación de macro-F1 post-cuantización.

Referencia permanente

El Glosario queda como consulta rápida de cualquier término técnico durante todo el onboarding y después.