Pipeline de Machine Learning

Ejecutar pipeline:

python -m notebooks.pipeline

Flujo:

flowchart LR
    A[Dataset UCI] --> B[EDA]
    B --> C[Preprocesamiento]
    C --> D[Entrenamiento y GridSearchCV]
    D --> E[Evaluacion]
    E --> F[Modelo exportado]
    F --> G[API FastAPI]

Etapas:

1. Obtencion de datos desde UCI o carga local desde data/raw/data.csv.
2. EDA con distribucion de clases y matriz de correlacion.
3. Preprocesamiento: exclusion de Enrolled, mapeo de Dropout a 1 y Graduate a 0, seleccion de las 18 variables usadas por la API, balanceo con SMOTE y division train/test.
4. Entrenamiento y comparacion de tres modelos con GridSearchCV.
5. Evaluacion con metricas de clasificacion.
6. Exportacion del modelo a models/pipeline_desercion.pkl (ignorado por Git; se regenera con el pipeline).

Experimentos y metricas

Modelos comparados:

El modelo seleccionado por mejor F1 en validacion cruzada es Random Forest. Para este problema se prioriza F1 y recall de la clase de desercion porque interesa detectar estudiantes en riesgo sin depender solo del accuracy.

Los resultados completos se guardan en:

data/results/resultados_experimentos.csv

Ejecucion local

Instalar dependencias:

python -m pip install -r requirements.txt

Generar dataset, graficos, resultados y modelo:

python -m notebooks.pipeline

Ejecutar pruebas:

python -m pytest -q

Levantar API:

python main.py

Documentacion interactiva:

http://localhost:8000/docs

Endpoints

Ejemplo minimo para POST /api/prediccion/:

{
  "estado_civil": 1,
  "modo_aplicacion": 1,
  "orden_aplicacion": 1,
  "curso": 1,
  "asistencia_diurna_nocturna": 1,
  "calificacion_previa": 1,
  "nota_admision": 150.0,
  "desplazado": 0,
  "necesidades_educativas_especiales": 0,
  "deudor": 0,
  "mensualidades_al_dia": 1,
  "genero": 1,
  "becario": 0,
  "edad_al_matricularse": 20,
  "unidades_curriculares_1er_sem_inscritas": 5,
  "unidades_curriculares_1er_sem_evaluaciones": 5,
  "unidades_curriculares_1er_sem_aprobadas": 5,
  "unidades_curriculares_1er_sem_nota": 15.0
}

Respuesta esperada:

{
  "estado": 200,
  "mensaje": "Prediccion realizada correctamente.",
  "datos": {
    "prediccion": "Graduado",
    "probabilidad": 0.07,
    "mensaje": "Prediccion procesada exitosamente por el modelo de IA."
  }
}

Arquitectura backend

• controllers: capa HTTP.
• services: reglas de negocio.
• providers: acceso al modelo entrenado.
• mappers: conversion entre DTOs y dominio.
• schemas: contratos de entrada y salida.
• domain: entidades y contrato de caracteristicas del modelo.
• core: respuestas, errores y seguridad compartida.

Estado de reproducibilidad

El repositorio no versiona data/raw/data.csv ni models/pipeline_desercion.pkl porque son artefactos generados. Para reproducir el backend desde cero se debe instalar dependencias y ejecutar:

python -m notebooks.pipeline
python -m pytest -q
python main.py