Propensión Documentación
Visión general
Propensión a compra, respuesta a campaña y upgrade de plan, con scores calibrados.
Esta referencia cubre 4 engines. Cada endpoint trae ruta, permiso, parámetros, respuesta y los errores posibles.
Propensión de compra
Propósito
Score de propensión de compra con aceleración dedicada vía competencia multi-modelo (Random Forest / XGBoost / red neuronal).
¿Por qué? Use este engine cuando necesite identificar qué clientes tienen mayor probabilidad de realizar un evento objetivo y no quiera apostar por un único algoritmo. Entrega scores calibrados por cliente, clasificación en tiers e importancia global de features, maximizando el desempeño predictivo con un enfoque ensemble. En la práctica, orienta la priorización de contactos y la segmentación de campañas hacia los clientes con mayor propensión.
¿Cómo? Entrena en paralelo Random Forest, XGBoost y una red neuronal profunda, con aceleración dedicada. El mejor modelo se selecciona automáticamente por ROC-AUC en un conjunto de holdout. La salida reúne scores calibrados, clasificación en tiers e importancia global de features.
Origen El método se apoya en XGBoost, propuesto por Chen y Guestrin (2016) en "XGBoost: A Scalable Tree Boosting System", y en los fundamentos de redes neuronales profundas consolidados por Goodfellow y coautores en "Deep Learning" (MIT Press, 2016).
Literatura de referencia
- Chen, T. & Guestrin, C. (2016). "XGBoost: A Scalable Tree Boosting System."
- Goodfellow, I. et al. (2016). "Deep Learning." MIT Press.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
label_column | string | sí | Nombre de la columna binaria 0/1 indicadora de compra. | |
algorithm | string | no | "auto" | Uno de auto, xgboost, random_forest, neural_net. auto entrena todos los modelos disponibles y se queda con el mejor por ROC-AUC. |
test_size | number | no | 0.2 | Fracción de filas reservada para el split de test. Entre 0.05 y 0.5. |
random_state | integer | no | 42 | Semilla aleatoria del split y del entrenamiento. Entero no negativo. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
customer_id | string | no | Identificador del cliente. Excluido de las features; cuando está presente, los scores por cliente se indexan por él en la salida. |
bought_product | integer | sí | Etiqueta binaria de compra, 0 o 1. El nombre real de la columna viene del param label_column. |
recency_days | integer | no | Días desde la última actividad del cliente. Cualquier columna numérica adicional se detecta y usa como feature. |
frequency_30d | integer | no | Número de compras en los últimos 30 días. |
monetary_total | number | no | Valor monetario total de las compras pasadas. |
Respuesta
En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).
Errores
403- la engine no está enallowed_enginesde tu suscripción.413- subida por encima demax_upload_mb.422- engine desconocida o inactiva en el catálogo.429- cuota diaria (max_jobs_per_day) o por minuto excedida.
La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.
curl -X POST "https://intelligence.echosistema.live/api/v1/propensity/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Propensión a campaña
Propósito
Propensión a responder a una campaña de marketing, vía XGBoost con aceleración dedicada y fallback en CPU.
¿Por qué? Sirve para predecir la probabilidad de que cada cliente responda a una campaña de marketing, optimizado para los grandes volúmenes típicos de campañas digitales. Con scores calibrados que reflejan chances reales de respuesta, permite concentrar el presupuesto en los deciles de mayor retorno y reducir el costo por respuesta.
¿Cómo? Un modelo XGBoost se entrena con aceleración dedicada sobre features normalizadas. Las probabilidades se calibran para representar chances reales, y el análisis de lift por decil evalúa la calidad del ranking generado.
Origen El método se basa en XGBoost, presentado por Chen y Guestrin (2016) en el artículo "XGBoost: A Scalable Tree Boosting System", publicado en la conferencia KDD.
Literatura de referencia
- Chen, T. & Guestrin, C. (2016). "XGBoost: A Scalable Tree Boosting System." KDD.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
label_column | string | sí | Nombre de la columna binaria 0/1 de respuesta a la campaña. | |
algorithm | string | no | "auto" | Uno de auto, xgboost, logistic, random_forest. auto usa XGBoost cuando está disponible, si no cae al pipeline alternativo. xgboost falla la validación si no está instalado. |
random_state | integer | no | 42 | Semilla aleatoria del split y del entrenamiento. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
customer_id | string | no | Identificador del cliente. Excluido de las features detectadas. |
responded_campaign | integer | sí | Etiqueta binaria de respuesta a la campaña, 0 o 1. El nombre real viene del param label_column. |
email_open_rate | number | no | Fracción de emails de marketing abiertos, 0..1. Cualquier columna numérica adicional se detecta y usa como feature. |
click_through_rate | number | no | Fracción de emails clickeados, 0..1. |
days_since_last_campaign | integer | no | Días desde el último contacto de campaña con el cliente. |
previous_campaigns_responded | integer | no | Conteo de campañas anteriores respondidas por el cliente. |
Respuesta
En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).
Errores
403- la engine no está enallowed_enginesde tu suscripción.413- subida por encima demax_upload_mb.422- engine desconocida o inactiva en el catálogo.429- cuota diaria (max_jobs_per_day) o por minuto excedida.
La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.
curl -X POST "https://intelligence.echosistema.live/api/v1/propensity_respond_campaign/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Score de propensión
Propósito
Score genérico de propensión a evento binario, con probabilidades calibradas y análisis de lift por deciles.
¿Por qué? Calcula propensity scores para eventos binarios, como compra, conversión o respuesta a una campaña, con probabilidades calibradas que reflejan chances reales y no solo un ranking relativo. Sirve para estimar de forma confiable la probabilidad de que un cliente realice una acción específica y priorizar a quién abordar primero.
¿Cómo? Un pipeline de clasificación combina Logistic Regression y Random Forest. La calibración isotónica garantiza que los scores representen probabilidades verdaderas, y el análisis de lift por decil mide el poder discriminativo del modelo.
Origen El concepto se remonta a Rosenbaum y Rubin (1983), quienes formalizaron el papel central del propensity score en estudios observacionales en el artículo "The Central Role of the Propensity Score in Observational Studies", publicado en Biometrika.
Literatura de referencia
- Rosenbaum, P. R. & Rubin, D. B. (1983). "The Central Role of the Propensity Score in Observational Studies." Biometrika, 70(1), 41-55.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
label_column | string | sí | Nombre de la columna objetivo binaria 0/1. | |
target_type | string | no | "custom" | Etiqueta del caso de uso: buy_product, respond_campaign, upgrade_plan o custom. No cambia el algoritmo, solo anota la salida. |
algorithm | string | no | "auto" | Uno de auto, logistic, random_forest. auto entrena ambos y se queda con el mejor por ROC-AUC. |
random_state | integer | no | 42 | Semilla aleatoria del split y del entrenamiento. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
customer_id | string | no | Identificador del cliente. Excluido de las features detectadas. |
bought_product | integer | sí | Etiqueta objetivo binaria, 0 o 1. El nombre real viene del param label_column. |
recency_days | integer | no | Días desde la última actividad del cliente. Cualquier columna numérica adicional se detecta como feature. |
frequency_30d | integer | no | Número de compras/eventos en los últimos 30 días. |
monetary_total | number | no | Valor monetario total asociado al cliente. |
avg_order_value | number | no | Valor promedio del pedido. |
email_open_rate | number | no | Fracción de emails de marketing abiertos, 0..1. |
Respuesta
En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).
Errores
403- la engine no está enallowed_enginesde tu suscripción.413- subida por encima demax_upload_mb.422- engine desconocida o inactiva en el catálogo.429- cuota diaria (max_jobs_per_day) o por minuto excedida.
La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.
curl -X POST "https://intelligence.echosistema.live/api/v1/propensity_score/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"Propensión a upgrade
Propósito
Propensión a hacer upgrade de plan/tier, vía XGBoost con aceleración dedicada y fallback en CPU.
¿Por qué? Especializado en predecir la probabilidad de que cada cliente haga upgrade de plan o tier, identificando a quienes tienen mayor propensión a migrar hacia planes superiores. Alimenta ofertas de upgrade dirigidas y aumenta el ingreso por cliente sin recurrir a campañas genéricas.
¿Cómo? Un modelo XGBoost se entrena con aceleración dedicada sobre features normalizadas, con el upgrade como variable objetivo. Las probabilidades se calibran y el análisis de lift por decil evalúa la calidad del ranking, con la misma arquitectura del engine de respuesta a campaña.
Origen El método se basa en XGBoost, presentado por Chen y Guestrin (2016) en el artículo "XGBoost: A Scalable Tree Boosting System", publicado en la conferencia KDD.
Literatura de referencia
- Chen, T. & Guestrin, C. (2016). "XGBoost: A Scalable Tree Boosting System." KDD.
Parámetros (params)
| Campo | Tipo | Obligatorio | Por defecto | Descripción |
|---|---|---|---|---|
label_column | string | sí | Nombre de la columna binaria 0/1 de upgrade de plan. | |
algorithm | string | no | "auto" | Uno de auto, xgboost, logistic, random_forest. auto usa XGBoost cuando está disponible, si no cae al pipeline alternativo. xgboost falla la validación si no está instalado. |
random_state | integer | no | 42 | Semilla aleatoria del split y del entrenamiento. |
Columnas de data[]
| Columna | Tipo | Obligatoria | Descripción |
|---|---|---|---|
customer_id | string | no | Identificador del cliente. Excluido de las features detectadas. |
upgraded_plan | integer | sí | Etiqueta binaria de upgrade de plan, 0 o 1. El nombre real viene del param label_column. |
tenure_days | integer | no | Días desde el inicio del plan del cliente. Cualquier columna numérica adicional se detecta como feature. |
feature_adoption_rate | number | no | Fracción de recursos del plan usados activamente, 0..1. |
usage_pct_of_quota | number | no | Porcentaje de la cuota de uso del plan actual consumida, 0..1. |
support_tickets_30d | integer | no | Número de tickets de soporte abiertos en los últimos 30 días. |
Respuesta
En modo asíncrono (por defecto), 202 Accepted con {"process_uuid", "result_url"}; el resultado sale en GET /api/v1/results/{process_uuid}. Con ?sync=true o ?dry_run=true la respuesta es 200 con el resultado inline (y 504 con el process_uuid si el worker no responde a tiempo).
Errores
403- la engine no está enallowed_enginesde tu suscripción.413- subida por encima demax_upload_mb.422- engine desconocida o inactiva en el catálogo.429- cuota diaria (max_jobs_per_day) o por minuto excedida.
La validación es fail-fast: un envío rechazado no tiene ningún efecto secundario.
curl -X POST "https://intelligence.echosistema.live/api/v1/propensity_upgrade_plan/process?dry_run=true&playground=true" \
-H "X-TENANT-KEY: $TENANT_KEY"