Inteligencia de Clientes Documentación

Engine

churn_deep

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Predicción de churn multi-modelo con aceleración dedicada (MLP, TabNet, Random Forest, XGBoost) y horizontes temporales.

Entrena una competencia de modelos de clasificación (MLP, TabNet, Random Forest, XGBoost, con aceleración dedicada cuando está disponible) contra una etiqueta binaria de churn, selecciona el mejor por ROC-AUC y escala la probabilidad resultante por múltiples horizontes de predicción.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

churn_label

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Etiquetado de churn por reglas determinísticas en tres modelos de negocio: ecommerce, saas, prepaid.

¿Por qué? Clasifica churn por reglas de negocio en tres modelos: e-commerce, SaaS y prepago, sin depender de un modelo entrenado. Entrega, por cliente, la etiqueta (churned, at_risk, declining o active), los indicadores que la sustentan y el campo binario churned (0/1), listo para usarse como variable objetivo en modelos predictivos downstream. También resume la distribución de etiquetas y el porcentaje de churn de la base, un termómetro rápido de retención.

¿Cómo? En e-commerce calcula días de inactividad, frecuencia de compra (transacciones por mes de antigüedad) y tendencia monetaria (variación del promedio de la segunda mitad de las transacciones frente a la primera), y aplica reglas con umbrales configurables: churned cuando la inactividad alcanza churn_days, at_risk cuando alcanza at_risk_days, declining cuando la tendencia cae por debajo de -0.2 o la frecuencia por debajo de 0.5 por mes, y active en el resto de los casos. En SaaS, el cliente es churned cuando canceló la suscripción. En prepago, es churned cuando el saldo llegó a cero y no hubo recarga en el ciclo.

Origen El enfoque sigue la línea de Hadden et al. (2007), "Computer Assisted Customer Churn Management", publicado en Computers & Operations Research.

Literatura de referencia

• Hadden, J. et al. (2007). "Computer Assisted Customer Churn Management." Computers & Operations Research, 34(10), 2902-2917.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

churn_prediction

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Clasificación de churn con detección automática de features, selección de algoritmo por validación cruzada y métricas solo de holdout.

¿Por qué? Predice la probabilidad de churn de cada cliente con clasificación supervisada, detectando automáticamente las features numéricas disponibles. Entrega la probabilidad y la etiqueta prevista por cliente, métricas completas de evaluación (AUC, precisión, recall, F1), la matriz de confusión y el ranking de feature importance, que explica qué comportamientos pesan más en el riesgo. Así, los equipos priorizan acciones de retención sobre los clientes de mayor riesgo antes de que se vayan.

¿Cómo? Un pipeline descarta las columnas de feature constantes, estandariza las demás y, en el modo auto, elige el algoritmo por ROC-AUC de validación cruzada solo sobre el conjunto de entrenamiento: Random Forest, XGBoost y Regresión Logística compiten, el empate se rompe por log-loss y luego por la simplicidad del modelo, y selection_reason registra qué regla decidió. El holdout se gasta una sola vez, en la evaluación final, así que las métricas y la matriz de confusión nunca incluyen filas de entrenamiento. Cada fila recibe una puntuación, pero toda predicción lleva su customer_id, la etiqueta real y el split del que proviene, de modo que una probabilidad in-sample nunca se ordena como si fuera out-of-sample. El peso de cada feature se mide por importancia de permutación sobre el holdout, y importance_method nombra el método realmente usado cuando el holdout es demasiado pequeño para ella.

Origen Los fundamentos provienen de Breiman (2001), "Random Forests", publicado en Machine Learning, y de Chen y Guestrin (2016), "XGBoost: A Scalable Tree Boosting System", presentado en KDD.

Literatura de referencia

• Breiman, L. (2001). "Random Forests." Machine Learning, 45(1), 5-32.
• Chen, T. & Guestrin, C. (2016). "XGBoost: A Scalable Tree Boosting System." KDD.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

clv_deep

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Predicción de Customer Lifetime Value multi-modelo con aceleración dedicada (LSTM, MLP, XGBoost) en múltiples horizontes.

Construye features RFM+ por cliente a partir del historial de transacciones con holdout temporal, luego compite regresores LSTM/MLP y XGBoost (con aceleración dedicada cuando está disponible) para predecir el CLV futuro, seleccionando el mejor modelo por MAE. Cae a un objetivo proxy de valor monetario cuando el historial es demasiado corto para un split temporal.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

cohort_analysis

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Triángulo de retención por cohorte de adquisición (mensual o semanal).

¿Por qué? Analiza cohortes de clientes para entender retención y comportamiento a lo largo del tiempo, comparando canales y camadas de clientes con la lente correcta. Entrega el triángulo de retención por cohorte, perfiles por cohorte (tamaño, retención promedio, vida mediana, churn en el primer mes) y un análisis de ciclo de vida que señala las cohortes de mejor y peor desempeño y la tendencia de retención. La métrica analizada es configurable entre retención, ingresos y frecuencia.

¿Cómo? Los clientes se agrupan en cohortes por el período de su primer evento, o por cualquier columna categórica como canal de adquisición o tipo de plan. Para cada cohorte se calcula la tasa de retención en cada período relativo al ingreso de la cohorte. El triángulo de retención se construye con agregación temporal configurable.

Origen La base conceptual es Fader y Hardie (2007), "How to Project Customer Retention", publicado en el Journal of Interactive Marketing.

Literatura de referencia

• Fader, P. S. & Hardie, B. G. S. (2007). "How to Project Customer Retention." Journal of Interactive Marketing, 21(1), 76-90.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

cohort_retention

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Matriz de retención y tasas de churn por cohorte de adquisición (día, semana o mes).

¿Por qué? Agrupa a los clientes por la fecha de su primer evento y muestra cuántos permanecen activos en los períodos siguientes, revelando si la retención mejora o empeora entre camadas. Entrega la matriz de retención (fracción de la cohorte original activa en cada período), las tasas de churn período a período, la curva promedio de retención entre cohortes y el half-life, el primer período en que la retención promedio cae por debajo del 50%. Es la base cuantitativa para metas de retención, proyecciones de base activa y evaluación del efecto de cambios en el producto.

¿Cómo? Cada cliente se asigna a una cohorte por la fecha de su primer evento, en la granularidad elegida (día, semana o mes), y cada evento recibe un offset en períodos desde esa fecha. La retención de la cohorte c en el período t es la fracción de clientes únicos activos sobre el tamaño de la cohorte, con retención igual a 1.0 en el período cero, y el churn período a período es 1 menos la razón entre retenciones consecutivas. La curva promedio agrega las cohortes con datos en cada período, y el half-life es el primer período en que ese promedio queda por debajo de 0.50 (nulo si nunca cae).

Origen La base conceptual es Fader y Hardie (2007), "How to Project Customer Retention", publicado en el Journal of Interactive Marketing.

Literatura de referencia

• Fader, P. S. & Hardie, B. G. S. (2007). "How to Project Customer Retention." Journal of Interactive Marketing, 21(1), 76-90.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

customer_360

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Perfil compuesto del cliente que fusiona las sub-engines RFM, loyalty, features y etiqueta de churn en un único score de salud.

Ejecuta internamente las engines RFM, Loyalty, Features y Churn Label sobre los mismos datos de transacción y fusiona las salidas por cliente en un perfil unificado, con score de salud 0-1 ponderado (30% loyalty, 25% RFM, 25% no-churn, 20% frecuencia de transacción) y un tier de salud (excellent/good/fair/poor/critical).

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

customer_clustering

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Segmentación de clientes con múltiples algoritmos de clustering y selección automática de K.

¿Por qué? Segmenta clientes por clustering con optimización automática, sin exigir grupos predefinidos, para descubrir los segmentos naturales de la base. Entrega la asignación de cluster por cliente, los centros de cada grupo, perfiles interpretados con etiquetas como Champions o At Risk y el silhouette score que mide la calidad de la separación. Alimenta campañas, priorización comercial y estrategias por perfil con grupos estadísticamente consistentes.

¿Cómo? Un pipeline normaliza las features (StandardScaler o MinMaxScaler), aplica PCA opcional para reducción de dimensionalidad y ejecuta múltiples algoritmos: K-Means, DBSCAN, clustering jerárquico y GMM. El mejor algoritmo y el número óptimo de clusters se eligen combinando Silhouette Score, índice Davies-Bouldin e índice Calinski-Harabasz.

Origen Los algoritmos se remontan a MacQueen (1967), "Some Methods for Classification and Analysis of Multivariate Observations", del Berkeley Symposium, que formalizó K-Means, y a Ester et al. (1996), "A Density-Based Algorithm for Discovering Clusters", de KDD, que introdujo DBSCAN.

Literatura de referencia

• MacQueen, J. (1967). "Some Methods for Classification and Analysis of Multivariate Observations." Berkeley Symposium.
• Ester, M. et al. (1996). "A Density-Based Algorithm for Discovering Clusters." KDD.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

customer_clv

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Customer Lifetime Value vía aproximaciones heurísticas BG/NBD + Gamma-Gamma basadas en RFM.

¿Por qué? Proyecta el Customer Lifetime Value de cada cliente a partir del historial transaccional, para dimensionar el presupuesto de adquisición, priorizar retención y medir la salud de largo plazo de la cartera. Entrega, por cliente, el CLV previsto en el horizonte configurado (12 meses por defecto), la probabilidad de una nueva compra, el número esperado de transacciones, el valor promedio previsto por pedido y el segmento de valor (High Value, Low Value, etc.), además de los agregados de la base.

¿Cómo? Usa métricas RFM como entrada y aplica una aproximación heurística del modelo BG/NBD para estimar el número esperado de transacciones futuras. El valor monetario esperado proviene de un estimador al estilo Gamma-Gamma con shrinkage, que estabiliza las estimaciones. Un descuento NPV convierte la proyección en valor presente del lifetime value.

Origen La base científica es Fader, Hardie y Lee (2005), "Counting Your Customers the Easy Way", publicado en Marketing Science, que estableció el framework BG/NBD para la predicción de compras futuras.

Literatura de referencia

• Fader, P. S., Hardie, B. G. S. & Lee, K. L. (2005). "Counting Your Customers the Easy Way." Marketing Science, 24(2), 275-284.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

customer_clv_features

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Extracción de features BG/NBD + Gamma-Gamma por cliente (frecuencia, recencia, T, valor monetario) para modelado de CLV.

¿Por qué? Extrae, por cliente, las features canónicas para modelar Customer Lifetime Value en los frameworks BG/NBD y Gamma-Gamma. Entrega frequency, recency, T, monetary_value, totales de transacciones y de gasto, y estadísticas de intervalo entre compras, además de un resumen de la base con promedios de las features y el conteo de compradores de una sola compra frente a recurrentes. Es el paso de preparación que deja los datos transaccionales listos para cualquier motor de predicción de CLV.

¿Cómo? Siguiendo la convención BG/NBD, frequency es el total de transacciones menos 1 (la primera compra se excluye), recency son los días entre la primera y la última compra, y T es la edad del cliente desde la primera compra hasta la fecha de referencia. monetary_value es el promedio de los montos de compra, acompañado de los totales de transacciones y de gasto. Para clientes con dos o más compras se calcula además el promedio y la desviación estándar de los intervalos entre compras consecutivas.

Origen Las definiciones siguen a Fader y Hardie (2005), "Counting Your Customers the Easy Way: An Alternative to the Pareto/NBD Model", publicado en Marketing Science, y a Fader y Hardie (2013), "The Gamma-Gamma Model of Monetary Value".

Literatura de referencia

• Fader, P. S. & Hardie, B. G. S. (2005). "Counting Your Customers the Easy Way: An Alternative to the Pareto/NBD Model." Marketing Science, 24(2), 275-284.
• Fader, P. S. & Hardie, B. G. S. (2013). "The Gamma-Gamma Model of Monetary Value." Working paper.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

customer_migration

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Matriz de transición de segmentos entre los dos períodos más recientes, con estado estacionario y proyección multi-período.

Compara el segmento de cada cliente (ej.: tier RFM) entre los dos últimos períodos presentes en los datos, construye una matriz de conteos/probabilidades de transición, clasifica a cada cliente como upgrade/downgrade/stable/churned/new y calcula la distribución de estado estacionario de la cadena de Markov más una proyección futura de project_periods pasos.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

engagement_velocity

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Velocidad y aceleración de engagement del cliente a partir de la cadencia de eventos y el gasto.

Para cada cliente, calcula la velocidad (1ª derivada) y la aceleración (2ª derivada) de los intervalos entre eventos y de los montos de las transacciones, clasifica al cliente en un cuadrante de engagement (stable, accelerating, decelerating, recovering, freefall) y asigna un score de momentum y una etiqueta de riesgo.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

features

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Ingeniería de features por cliente a partir del historial bruto de compras.

¿Por qué? Transforma datos transaccionales crudos en un perfil de comportamiento por cliente, eliminando el trabajo manual de feature engineering. Produce una matriz de una fila por cliente con 10 métricas de ingeniería en cuatro dimensiones: volumen, temporal, frecuencia y diversidad de productos. La matriz está diseñada para alimentar modelos downstream como predicción de churn, segmentación y CLV, y viene acompañada de un resumen de la base con promedios de gasto y de transacciones por cliente.

¿Cómo? Por cliente, calcula seis métricas de volumen (conteo, suma, promedio, máximo, mínimo y desviación estándar muestral de las transacciones) y dos temporales (días desde la primera y desde la última compra respecto de la fecha de referencia). El intervalo promedio entre compras consecutivas cubre la dimensión de frecuencia, con valor cero para quien tiene una sola transacción. La diversidad es el conteo de productos distintos, calculado cuando la columna product_id está presente.

Origen La práctica sigue a Kuhn y Johnson (2019), "Feature Engineering and Selection: A Practical Approach for Predictive Models", publicado por CRC Press.

Literatura de referencia

• Kuhn, M. & Johnson, K. (2019). "Feature Engineering and Selection: A Practical Approach for Predictive Models." CRC Press.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

loyalty

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Score de fidelidad en tiers vía normalización MinMax ponderada de 5 métricas del cliente.

¿Por qué? Calcula un índice compuesto de fidelidad por cliente para sustentar programas de fidelidad, beneficios por tier y alertas sobre clientes valiosos en riesgo. Combina cinco métricas de comportamiento en un score ponderado: total de compras (peso 0.30), frecuencia de visitas (0.25), ticket promedio (0.10), diversidad de productos (0.10) y recencia (0.25), con pesos configurables. Cada cliente recibe el score final en [0, 1] y uno de cinco tiers: Platinum (>= 0.80), Gold (>= 0.60), Silver (>= 0.40), Bronze (>= 0.20) y At-Risk (< 0.20).

¿Cómo? Extrae por cliente el total de compras, la frecuencia de visitas, el ticket promedio, la diversidad de productos y los días desde la última compra. Cada métrica se normaliza a [0, 1] vía MinMax, con la recencia invertida (cuanto más reciente, mejor) y valor 0.5 cuando máximo y mínimo coinciden. La suma ponderada, con pesos normalizados para sumar 1.0, genera el score final acotado a [0, 1], y umbrales fijos definen los cinco tiers.

Origen La inspiración conceptual es Sharp (2010), "How Brands Grow", publicado por Oxford University Press.

Literatura de referencia

• Sharp, B. (2010). "How Brands Grow." Oxford University Press.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

nps

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Net Promoter Score calculado a partir de respuestas 0-10 de encuesta.

¿Por qué? Mide lealtad y satisfacción con la métrica clásica de Net Promoter Score, a partir de la pregunta "del 0 al 10, ¿qué tan probable es que recomiendes nuestro producto o servicio?". Entrega el NPS global entre -100 y +100 con clasificación cualitativa, el conteo de promotores, pasivos y detractores, la clasificación individual de cada encuestado y, con group_by, el NPS por cualquier dimensión, como producto, categoría o región. Permite comparar la satisfacción entre líneas de negocio y seguir la evolución de la lealtad de la base.

¿Cómo? Cada respuesta se clasifica por el score: 9 o 10 es promotor, 7 u 8 es pasivo, 6 o menos es detractor. El NPS es la diferencia entre promotores y detractores dividida por el total de respuestas, por 100; los pasivos cuentan en el denominador pero no en el numerador. El valor recibe una franja cualitativa (>= 70 Excelente, >= 50 Muy Bueno, >= 30 Bueno, >= 0 Necesita Mejorar, debajo de 0 Crítico) y, cuando hay agrupamiento, la misma fórmula se aplica de forma independiente a cada grupo.

Origen La métrica fue propuesta por Reichheld (2003) en "The One Number You Need to Grow", publicado en Harvard Business Review.

Literatura de referencia

• Reichheld, F. F. (2003). "The One Number You Need to Grow." Harvard Business Review, 81(12), 46-54.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

purchasing_segment

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Segmentación de comportamiento de compra vía clustering multi-algoritmo con aceleración dedicada.

¿Por qué? Segmentación conductual de compras con aceleración dedicada, orientada a e-commerce, para guiar campañas por perfil de compra e identificar clientes en riesgo. Asigna a cada cliente un segmento con nombre (como Premium Tech Enthusiasts o At-Risk Low Spenders) y entrega perfiles con promedios de compras, ticket, recencia, frecuencia de compra y categorías predominantes. El número de segmentos puede fijarse o detectarse automáticamente.

¿Cómo? Primero construye features al estilo RFM por cliente: recencia, frecuencia, valor monetario, diversidad de productos, ticket promedio y similares. Luego clusteriza con K-Means y DBSCAN sobre aceleración dedicada. El mejor resultado se selecciona automáticamente por silhouette score.

Origen Las raíces del método están en MacQueen (1967), "Some Methods for Classification and Analysis of Multivariate Observations", que formalizó K-Means, y en Bult y Wansbeek (1995), "Optimal Selection for Direct Mail", de Marketing Science, base de la segmentación por comportamiento de compra.

Literatura de referencia

• MacQueen, J. (1967). "Some Methods for Classification and Analysis of Multivariate Observations."
• Bult, J. R. & Wansbeek, T. (1995). "Optimal Selection for Direct Mail." Marketing Science.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

rfm

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Segmentación RFM (Recencia, Frecuencia, Monetario) de clientes vía score por cuantiles.

¿Por qué? Segmenta la base de clientes según las tres dimensiones clásicas del comportamiento de compra: Recencia (cuándo fue la última compra), Frecuencia (cuántas veces compró el cliente) y Monetario (cuánto gastó en total). Entrega, por cliente, los scores R, F y M, la clase concatenada (por ejemplo 543), el score RFM total y un tier accionable: Champion, Loyal, Potential Loyalist, Needs Attention o At Risk, junto con la distribución de tiers de la base. Es la forma más directa de priorizar campañas de retención, reactivación y ofertas segmentadas sin entrenar ningún modelo.

¿Cómo? Agrega las transacciones por cliente: R como días desde la última compra, F como conteo de transacciones y M como suma de los montos. Cada dimensión se discretiza en scores de 1 a N mediante cuantiles con interpolación lineal, con F y M crecientes (mayor es mejor) y R invertido (menor es mejor). El tier surge de franjas porcentuales sobre el máximo posible del score combinado: Champion >= 80%, Loyal >= 60%, Potential Loyalist >= 40%, Needs Attention >= 25% y At Risk por debajo.

Origen El método se apoya en Bult y Wansbeek (1995), "Optimal Selection for Direct Mail", publicado en Marketing Science, referencia clásica de la selección de clientes por RFM en el marketing directo.

Literatura de referencia

• Bult & Wansbeek (1995). "Optimal Selection for Direct Mail." Marketing Science, 14(4), 378-394.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

segment

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Segmentación genérica de clientes vía clustering multi-algoritmo con aceleración dedicada.

¿Por qué? Segmentación de clientes con aceleración dedicada, indicada para bases voluminosas donde el clustering debe ejecutarse rápido sin sacrificar calidad estadística. Entrega la asignación de cluster por cliente, los centros de los grupos, el silhouette por muestra, el índice Davies-Bouldin y etiquetas interpretables para cada segmento (por ejemplo VIP, Regular, Inactivo). El número óptimo de clusters se determina automáticamente.

¿Cómo? Ejecuta múltiples algoritmos de clustering (K-Means, DBSCAN, jerárquico y GMM) sobre aceleración dedicada, con PCA para reducción de dimensionalidad. El mejor algoritmo y el número de clusters se seleccionan por silhouette score. Cuando la aceleración no está disponible, una contingencia automática de procesamiento asume la ejecución.

Origen Los algoritmos se remontan a MacQueen (1967), "Some Methods for Classification and Analysis of Multivariate Observations", que formalizó K-Means, y a Ester et al. (1996), "A Density-Based Algorithm for Discovering Clusters", de KDD, que introdujo DBSCAN.

Literatura de referencia

• MacQueen, J. (1967). "Some Methods for Classification and Analysis of Multivariate Observations."
• Ester, M. et al. (1996). "A Density-Based Algorithm for Discovering Clusters." KDD.

Parámetros (params)

Columnas de data[]

El spec de esta engine no declara columnas fijas: consulta el ejemplo abajo.

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

segment_cluster_profiles

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Perfil estadístico y features discriminantes de cada cluster de clientes ya calculado.

¿Por qué? Genera perfiles estadísticos que explican qué diferencia a cada cluster de una segmentación, volviendo interpretables y nombrables los clusters numéricos. Entrega estadísticas globales y por cluster para cada feature, Z-scores discriminantes, el ranking de las features que más distinguen a cada grupo y una identidad descriptiva por cluster, como "High revenue, Low recency, High frequency". Esencial para interpretar y nombrar la salida de cualquier motor de segmentación.

¿Cómo? Calcula promedio, mediana y desviación estándar de cada feature numérica, a nivel global y por cluster. El Z-score discriminante mide a cuántas desviaciones estándar está el promedio del cluster respecto del promedio global, con dirección clasificada como por encima del promedio (z > +0.5), por debajo (z < -0.5) o en el promedio. Las features se rankean por |Z-score| descendente, las top N (5 por defecto) entran en la identidad, y la cadena descriptiva concatena "High/Low" por feature según el signo.

Origen El trasfondo es Jain (2010), "Data Clustering: 50 Years Beyond K-Means", publicado en Pattern Recognition Letters.

Literatura de referencia

• Jain, A. K. (2010). "Data Clustering: 50 Years Beyond K-Means." Pattern Recognition Letters, 31(8), 651-666.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

segmentation_report

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Reporte consolidado de la distribución de clientes y métricas entre segmentos existentes.

¿Por qué? Consolida asignaciones cliente-segmento en un informe ejecutivo: cuánto vale cada segmento y cómo la base migra entre ellos. Entrega la distribución por segmento (conteo y porcentaje), agregados estadísticos de cada métrica numérica por segmento, el segmento líder según la métrica primaria y, opcionalmente, la matriz de migración entre segmentos anteriores y actuales. Es la fotografía lista para reuniones de negocio sobre cualquier segmentación ya calculada.

¿Cómo? Para cada segmento calcula conteo y porcentaje de clientes, y para cada métrica numérica agrega suma, promedio, mediana, mínimo, máximo y desviación estándar. El top segmento es el de mayor suma en la métrica primaria. Cuando se proporciona el mapa previous_segments, construye la matriz de migración contando las transiciones de segmento antiguo a nuevo, con los clientes sin segmento anterior rastreados como new.

Origen El marco conceptual es Wedel y Kamakura (2000), "Market Segmentation: Conceptual and Methodological Foundations", publicado por Springer.

Literatura de referencia

• Wedel, M. & Kamakura, W. A. (2000). "Market Segmentation: Conceptual and Methodological Foundations." Springer.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

subscription_engine

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Parámetros óptimos de suscripción/recurrencia por par cliente-producto.

Para cada par (customer_id, product_id) con historial suficiente, deriva la frecuencia ideal de entrega a partir de una media móvil ponderada de los intervalos de compra, arma una tabla progresiva de descuento por fidelidad, proyecta LTV a 3/6/12/24 meses, estima ingresos recurrentes mensuales y, cuando prescription_date está presente, calcula alertas de vencimiento de receta médica y recordatorios de renovación.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.

Engine

survival_kaplan_meier

Grupo

customer_intelligence

Auth

X-TENANT-KEY | Authorization: Bearer

Entrada

JSON inline (data[]) o archivo .json/.csv/.parquet vía multipart/form-data

Modos

asíncrono (202) · ?sync=true (200) · ?dry_run=true (200, efímero)

Propósito

Análisis de supervivencia Kaplan-Meier para estudios de vida útil del cliente / churn.

¿Por qué? Estima la función de supervivencia de los clientes para estudios de lifetime y churn, respondiendo cuánto duran los clientes y qué segmentos retienen mejor. Entrega la tabla de supervivencia con población en riesgo y probabilidad acumulada en cada tiempo, la supervivencia mediana, tasas en hitos como 1 y 3 años y, con stratify_by, curvas separadas por segmento o plan con comparación estadística entre grupos. Base sólida para políticas de retención y proyecciones de ingresos.

¿Cómo? Usa el estimador Kaplan-Meier (product-limit) para la función de supervivencia S(t), tratando correctamente las observaciones censuradas, los clientes que aún no hicieron churn. Los intervalos de confianza provienen de la varianza de Greenwood, y también se calcula la tasa de hazard instantánea h(t). El test log-rank verifica si la diferencia de supervivencia entre grupos es estadísticamente significativa.

Origen El método proviene de Kaplan y Meier (1958), "Nonparametric Estimation from Incomplete Observations", publicado en el Journal of the American Statistical Association.

Literatura de referencia

• Kaplan, E. L. & Meier, P. (1958). "Nonparametric Estimation from Incomplete Observations." Journal of the American Statistical Association, 53(282), 457-481.

Parámetros (params)

Columnas de data[]

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á en allowed_engines de tu suscripción.
• 413 - subida por encima de max_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.