E-commerce Conversion ML

Sistema reproducible de machine learning para estimar la probabilidad de conversion de una sesion de comercio electronico. El proyecto cubre descarga y validacion de datos, pipelines sin fuga, comparacion y calibracion de modelos, estudio de ablacion, politica de decision sensible a costes, incertidumbre bootstrap, pruebas de estres por cohortes, monitorizacion de deriva, API y dashboard interactivo.

No representa un sistema usado por una empresa. Es un proyecto de portfolio construido sobre datos publicos y todas las metricas proceden de la ejecucion incluida.

Problema

La variable Revenue indica si una sesion termino en compra. El objetivo tecnico es ordenar sesiones por probabilidad estimada y estudiar como convertir esa probabilidad en una decision reproducible. El modelo no debe usarse para tomar decisiones sobre personas ni para atribuir causalidad.

El proyecto separa deliberadamente dos escenarios:

Variante	Variables	Uso
Full-session benchmark	17	Techo de rendimiento que incluye PageValues
Deployment-safe	16	Variante operativa que excluye PageValues por disponibilidad dudosa en tiempo real

Esta ablacion evita presentar como desplegable un resultado que depende de una variable potencialmente calculada al final de la sesion.

Arquitectura

flowchart LR
    A[UCI download] --> B[Schema and range checks]
    B --> C[Stratified train validation test]
    C --> D[Preprocessing inside pipelines]
    D --> E[Baselines and HGB tuning]
    E --> F[Feature-availability ablation]
    F --> G[Calibration selection]
    G --> H[F1 and cost policies]
    H --> I[Untouched test and bootstrap]
    I --> J[Streamlit dashboard]
    I --> K[FastAPI scoring]
    I --> L[PSI drift reference]

Loading

Tecnologias

Python, pandas, NumPy, scikit-learn, Plotly, Matplotlib, Streamlit, FastAPI, Pydantic, Docker, pytest, Ruff y GitHub Actions.

El stack numerico que serializa el modelo se fija a las versiones de entrenamiento porque los estimadores joblib no garantizan compatibilidad entre versiones. El bundle registra Python, scikit-learn, joblib, NumPy y pandas para auditar el entorno.

Datos

Se utiliza Online Shoppers Purchasing Intention Dataset de UCI: 12.330 sesiones, 17 variables de entrada y una etiqueta binaria. El CSV original no se versiona; el comando de descarga usa TLS verificado y genera un manifiesto con hashes.

Fuente: Sakar, C. y Kastro, Y. (2018), UCI Machine Learning Repository, DOI 10.24432/C5F88Q, licencia CC BY 4.0. Consulta la ficha de datos.

Metodologia

• Split estratificado reproducible: 60% entrenamiento, 20% validacion y 20% test intacto.
• Imputacion, escalado y one-hot encoding dentro de cada Pipeline.
• Baseline de prevalencia, regresion logistica balanceada y HistGradientBoostingClassifier.
• Busqueda de hiperparametros con validacion cruzada estratificada solo en entrenamiento.
• Comparacion de calibracion por Brier score en validacion.
• Dos umbrales fijados en validacion: maximo F1 y coste normalizado FN=5, FP=1.
• Ablacion de PageValues antes de seleccionar la variante de despliegue.
• Intervalos de confianza al 95% mediante 500 remuestras bootstrap del test.
• Prueba de estres mensual con cohortes de muestra limitada marcadas explicitamente.
• Perfil de referencia y Population Stability Index para vigilar cambios de distribucion.

El detalle completo esta en Metodologia y Model Card.

Resultados reales

El benchmark de sesion completa obtiene mayor rendimiento, pero no se considera seguro para scoring temprano. El modelo deployment-safe sacrifica rendimiento para respetar la disponibilidad de variables.

Test intacto, umbral F1	Full-session	Deployment-safe
Average precision	0.7392	0.3513
ROC-AUC	0.9293	0.7602
Brier score	0.0715	0.1163
F1	0.6599	0.3961
Expected calibration error	0.0155	0.0213

Con la politica de coste normalizado, el umbral del modelo operativo es 0.14: precision 0.2609, recall 0.7801 y F1 0.3911. Las unidades de coste son un escenario analitico, no economia observada de una empresa.

Bootstrap del modelo operativo	IC 95%
ROC-AUC	0.7372 - 0.7823
Average precision	0.3028 - 0.4008
Brier score	0.1088 - 0.1248
F1 al umbral de coste	0.3582 - 0.4234

La prueba mensual no se interpreta de forma ingenua: febrero obtiene AP=1.0 con solo 38 sesiones y un positivo, por lo que se etiqueta como muestra limitada. Las cohortes robustas requieren al menos 200 sesiones y 20 positivos.

Dashboard

La aplicacion Streamlit incluye cuatro espacios de trabajo:

• Scoring: prediccion individual con seleccion de modelo y politica de umbral.
• Models: ablacion, calibracion, incertidumbre y estres por cohortes.
• Costs: simulador interactivo de costes de falsos positivos y negativos.
• Drift: diagnostico PSI de un lote nuevo frente al perfil de entrenamiento.

Instalacion

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt

Ejecucion

python -m src.download_data
python -m src.train
streamlit run app.py

Prediccion por lotes:

python -m src.predict --input data/new_sessions.csv --output reports/predictions.csv

API y documentacion OpenAPI:

python -m uvicorn src.api:app --reload
# http://localhost:8000/docs

Despliegue local con Docker:

docker build -t conversion-risk-api .
docker run --rm -p 8000:8000 conversion-risk-api

Consulta los endpoints y contratos en docs/API.md.

Calidad

python -m ruff check .
python -m pytest

La suite actual contiene 16 pruebas para pipelines, metricas, calibracion, costes, deriva y API. GitHub Actions ejecuta lint y tests en cada pull request y en main.

Estructura

src/        descarga, validacion, entrenamiento, gobernanza, monitorizacion y API
tests/      pruebas unitarias y de endpoints
data/       manifiesto de procedencia; el CSV fuente no se versiona
models/     bundle reproducible con modelos, umbrales y perfil de referencia
reports/    metricas, predicciones, tablas y figuras generadas
docs/       data card, metodologia, model card, API y capturas
app.py      dashboard Streamlit
Dockerfile  imagen de la API

Limitaciones

• UCI solo aporta el mes, no una fecha exacta; no puede construirse un holdout temporal real.
• La politica de costes es una simulacion normalizada y requiere datos economicos reales antes de uso operativo.
• El PSI detecta cambio de distribucion, pero no demuestra por si solo una caida de rendimiento.
• Los intervalos bootstrap cuantifican variacion muestral del mismo test, no incertidumbre entre mercados o periodos futuros.
• Un despliegue real exigiria revision de privacidad, consentimiento, sesgos, latencia y disponibilidad de variables.

Autor

Desarrollado por 0227lia como proyecto de portfolio de Ciencia de Datos.