Resumen
Este documento inventaría el código existente del proyecto Pedido Sugerido en el repositorio GitLab DimAje/aje-analytics-model-pedido-sugerido (rama main). Se identifican los scripts canónicos multi-país que servirán como base del Desarrollo del Nivel 1, las variantes histórico-experimentales por país que quedan fuera del alcance del refactor, y los componentes de infraestructura (CDK) y CI/CD que orquestan la ejecución.
Conclusiones clave:
- Versión canónica identificada: los tres scripts en
cicd/src/(PS_MP_1_limpieza.py,PS_MP_2_modelado.py,PS_MP_3_reglas_negocio.py) son la versión consolidada multi-país. Derivan por refactor de los TEST de México (PS_Mexico/TEST_PS_MX_*.py), que la propuesta v2 designa como fuente de verdad de la lógica de negocio. - Variantes por país (
PS_CostaRica/,PS_Ecuador/,PS_Guatemala/,PS_Nicaragua/,PS_Panama/,PS_Peru/,PS_Mexico/): son la implementación histórica país-por-país que el proyecto Nivel 1 reemplaza con un solo código parametrizado. No requieren modificación; quedan en el repo como referencia. - Infraestructura: un único stack CDK (
AjePsInfraStackeninfra/infra/infra_stack.py) provisiona ECR, S3, Lambda trigger, EventBridge schedules por país, DynamoDB de configuración, CodeBuild projects (deploy stack / build / deploy SM pipeline), CodePipeline y CloudWatch alarmas. Ya desplegado en la cuenta dev832257724409.
Estructura del repositorio
aje-analytics-model-pedido-sugerido/
├── cicd/ · build y deploy del SageMaker Pipeline
│ ├── docker/ · imágenes base (processing + spark)
│ ├── scripts/ · build / push ECR + upsert SM Pipeline
│ └── src/ · scripts canónicos multi-país ★
├── infra/ · CDK app (AjePsInfraStack)
│ ├── app.py
│ ├── infra/infra_stack.py
│ └── lambda/lambda.py · trigger function
├── PS_PaisesConfig/ · configs históricos (formato libre)
├── PS_PaisesConfigDynamo/ · configs cargados a DynamoDB ★
├── PS_<País>/ · scripts/notebooks por país (referencia)
└── docs/ · documentación del proyecto
★ Componentes que están en el alcance directo del Desarrollo Nivel 1.
Inventario por etapa del pipeline
El SageMaker Pipeline tiene cuatro etapas conceptuales. Las tres primeras corren como ProcessingStep en SageMaker; la cuarta es el Pipeline mismo (orquestación).
Etapa 1 · Limpieza
| Atributo | Valor |
|---|---|
| Script canónico | cicd/src/PS_MP_1_limpieza.py |
| Líneas de código | 351 |
| Imagen Docker | cicd/docker/Dockerfile.processing (Python 3.9-slim + pandas + awswrangler) |
| Inputs | maestro · visitas · ventas · stock (S3) + config país (DynamoDB) |
| Output | EC_maestro_productos.csv · CSVs por ruta · parquet de ventas |
| Variantes históricas | PS_Mexico/TEST_PS_MX_1_limpieza.py (canónico per propuesta), PS_Ecuador/TEST_PS_EC_1_limpieza.py, PS_Peru/TEST_PS_PE_1_limpieza.py, PS_CostaRica/TEST_PS_CR_1_limpieza.py, PS_Guatemala/TEST_PS_GT_1_limpieza.py, PS_Nicaragua/TEST_PS_NI_1_limpieza.py, PS_Panama/TEST_PS_PA_1_limpieza.py, PS_Econoredes_Ecuador/TEST_PS_EC_ECO_1_limpieza.py |
| Origen del canónico | Refactor de PS_MultiPais/TEST_PS_MP_1_limpieza.py |
Etapa 2 · Modelado
| Atributo | Valor |
|---|---|
| Script canónico | cicd/src/PS_MP_2_modelado.py |
| Líneas de código | 198 |
| Imagen Docker | cicd/docker/Dockerfile.spark (Python 3.9 + PySpark 3.3.4 + Java JDK) |
| Algoritmo | ALS (Alternating Least Squares) para sistema de recomendación |
| Inputs | Outputs de Limpieza (CSVs por ruta) |
| Output | Modelo entrenado + matriz de recomendaciones top-N por cliente |
| Variantes históricas | PS_<País>/TEST_PS_<PAÍS>_2_modelado.py para los 7 países |
| Origen del canónico | Refactor de PS_MultiPais/TEST_PS_MP_2_modelado.py |
Etapa 3 · Reglas de Negocio
| Atributo | Valor |
|---|---|
| Script canónico | cicd/src/PS_MP_3_reglas_negocio.py |
| Líneas de código | 415 (la etapa más compleja del pipeline) |
| Imagen Docker | cicd/docker/Dockerfile.processing (misma que Limpieza) |
| Función | Aplica filtros, pesos, blocking lists y reglas comerciales sobre las recomendaciones del modelo |
| Inputs | Outputs de Modelado + maestro + recurrentes + stock + skus_sin_precio |
| Output | Recomendaciones finales por cliente listas para entrega al área comercial |
| Variantes históricas | PS_<País>/TEST_PS_<PAÍS>_3_reglas_negocio.py para los 7 países |
| Origen del canónico | Refactor de PS_MultiPais/TEST_PS_MP_3_reglas_negocio.py |
Etapa 4 · Orquestación
| Atributo | Valor |
|---|---|
| Definición del pipeline | cicd/scripts/deploy_sagemaker_pipeline.py (206 LOC) |
| Nombre del SM Pipeline | aje-dev-ps-pipeline-sagemaker |
| Tipo | SageMaker Pipeline con tres ProcessingStep secuenciales |
| Trigger por país | Lambda aje-dev-ps-triggerfunction-lambda (infra/lambda/lambda.py, 41 LOC) que invoca sagemaker:StartPipelineExecution |
| Schedule | EventBridge rules escalonadas por país (CR 10:00 UTC → PE 11:00 UTC, cada 10 min, L-V) |
Scripts canónicos · cicd/src/
Los tres scripts canónicos siguen un patrón uniforme:
- Cargar la configuración del país desde DynamoDB (tabla
aje-dev-ps-configtable-dynamodb). - Validar inputs en S3.
- Procesar (extracción, transformación, modelado o aplicación de reglas).
- Escribir outputs en S3 bajo el prefix
ps-pipeline/<país>/<etapa>/.
| Archivo | LOC | Funciones principales |
|---|---|---|
cicd/src/PS_MP_1_limpieza.py |
351 | load_pais_config, comprobar_inputs, extraer_datos, procesar_pais, main |
cicd/src/PS_MP_2_modelado.py |
198 | Entrenamiento ALS con PySpark |
cicd/src/PS_MP_3_reglas_negocio.py |
415 | Filtros comerciales, pesos por marca, blocking lists |
Infraestructura · CDK
| Archivo | LOC | Contenido |
|---|---|---|
infra/app.py |
25 | Entry point del CDK app · acepta context stage, region, account, gitlab_connection_arn |
infra/infra/infra_stack.py |
698 | AjePsInfraStack · provisiona todos los recursos AWS del proyecto |
infra/lambda/lambda.py |
41 | Lambda trigger que dispara sagemaker:StartPipelineExecution con el code_country del evento |
Recursos provisionados por AjePsInfraStack (resumen):
- 2 ECR repos (
aje-dev-ps-processing,aje-dev-ps-spark) - 1 S3 bucket para artifacts de CodePipeline (
aje-dev-ps-codepipelinebucket-s3) - 1 Lambda + 7 EventBridge rules (una por país, schedules escalonados)
- 1 DynamoDB table (
aje-dev-ps-configtable-dynamodb) - 3 CodeBuild projects (deploy stack · build images · deploy SM pipeline)
- 1 CodePipeline (
aje-dev-ps-pipeline-codepipeline) con 4 stages (Source · DeployStack · Build · Deploy) - 6 IAM roles internos + 1 SageMaker execution role (
aje-dev-ps-sagemaker-executionrole-iam) - 1 SNS topic + 2 CloudWatch alarms + 1 dashboard
CI/CD · cicd/
Buildspecs
| Archivo | Propósito | Comando principal |
|---|---|---|
cicd/buildspec-deploystack.yml |
Despliega AjePsInfraStack vía cdk deploy |
cd infra && cdk synth -c stage=$STAGE ... && cdk deploy ... |
cicd/buildspec-build.yml |
Construye y pushea imágenes Docker a ECR | bash cicd/scripts/build_push_ecr_images.sh |
cicd/buildspec-deploy.yml |
Upserta el SageMaker Pipeline definition | python3 -m scripts.deploy_sagemaker_pipeline |
Scripts auxiliares
| Archivo | LOC | Función |
|---|---|---|
cicd/scripts/build_push_ecr_images.sh |
41 | docker build + docker push para processing y spark |
cicd/scripts/deploy_sagemaker_pipeline.py |
206 | Genera el JSON definition del SM Pipeline (usando SageMaker SDK) y hace upsert |
Imágenes Docker
| Archivo | Base | Tamaño en ECR | Usado por |
|---|---|---|---|
cicd/docker/Dockerfile.processing |
public.ecr.aws/docker/library/python:3.9-slim |
~332 MB | Limpieza, Reglas de Negocio |
cicd/docker/Dockerfile.spark |
public.ecr.aws/docker/library/python:3.9-slim + Java JDK + PySpark |
~588 MB | Modelado |
Configuración por país
Hay dos copias de la configuración por país, en formatos distintos:
| Carpeta | Formato | Uso |
|---|---|---|
PS_PaisesConfig/ |
JSON nativo + paises_config.json agregado |
Histórico · referencia para los notebooks por país |
PS_PaisesConfigDynamo/ |
JSON con tipos DynamoDB ({"S":...}, {"N":...}, {"L":[...]}) |
Cargado a la tabla aje-dev-ps-configtable-dynamodb · usado por los scripts canónicos en runtime |
Países cubiertos (uno por archivo): CostaRica, Ecuador, Guatemala, Mexico, Nicaragua, Panama, Peru. 7 países total, alineado con el alcance del proyecto.
Campos relevantes de cada config (extraídos de PS_Ecuador_config.json como ejemplo):
| Campo | Tipo | Ejemplo |
|---|---|---|
code_country |
string | EC (partition key) |
nombre |
string | Ecuador |
s3_prefix |
string | pedido_sugerido/ecuador/ |
visitas_key |
string | visitas_ecuador000 |
ventas_keys |
list of strings | ["ventas_ecuador000"] |
maestro_csv |
string | EC_maestro_productos.csv |
compania_ventas_int |
number | 90 (filtro de cod_compania) |
rutas |
list of numbers | [1008, 1108, 1208, ...] (filtro de rutas válidas) |
stock_s3 |
string | s3://aje-dev-analytics-artifacts-s3/pedido_sugerido/ecuador/D_stock_ec.csv |
low_sku_threshold |
number | 10 |
s3_output_prefix |
string | PS_Ecuador/Output/PS_piloto_v1/ |
s3_output_data_prefix |
string | PS_Ecuador/Output/PS_piloto_data_v1/ |
pe_special |
map (solo Perú) | Reglas especiales de Perú: blocking lists, allowlist Excel, sucursales de Lima |
has_pedido_recurrente |
bool | true (activa una sección extra de reglas) |
Variantes históricas por país · referencia
Los siguientes archivos son la implementación previa del pipeline, hechos país-por-país antes del refactor multi-país. No están en el alcance del Desarrollo Nivel 1 y quedan en el repo como referencia histórica.
| Carpeta | Archivos | Tipo dominante |
|---|---|---|
PS_CostaRica/ |
4 archivos (1 PROD .ipynb · 3 TEST .py · 1 orquestador .ipynb) |
TEST en Python · PROD en notebook |
PS_Ecuador/ |
4 archivos · mismo patrón | |
PS_Econoredes_Ecuador/ |
4 archivos · variante de Ecuador para canal "Econoredes" | |
PS_Guatemala/ |
4 archivos · mismo patrón | |
PS_Mexico/ |
9 archivos (incluye PROD canónico de la propuesta v2): PROD_PS_Mexico.ipynb, TEST_PS_MX_1..4, PS_MX_script_test.py, D_PS_Mexico_2024-*.ipynb (dos copias históricas), PROD_PS_Mexico copy_2026-02-27.ipynb |
TEST en Python · PROD en notebook (más copias de trabajo) |
PS_MultiPais/ |
4 archivos TEST_PS_MP_* |
Precursores de cicd/src/* · primer intento multi-país |
PS_Nicaragua/ |
4 archivos · mismo patrón | |
PS_Panama/ |
4 archivos · mismo patrón | |
PS_Peru/ |
5 archivos (incluye TEST_PS_PE_solo_paso3.ipynb · sesión de debugging del paso 3) |
|
PEs_Ecuador/ |
3 archivos · proyecto separado Pedido Estratégico Ecuador (PEs), distinto de Pedido Sugerido | Fuera del alcance del proyecto actual |
Reporting/ |
3 archivos · reportes de todos los países | Fuera del alcance del refactor; potencial trabajo futuro |
Versión canónica · justificación
La propuesta v2 (sección "Supuestos y Condiciones") establece:
Los scripts actuales de México (limpieza, modelado, reglas de negocio) son la versión correcta y vigente de la lógica de negocio a aplicar a los demás países.
Sobre esta base, el código canónico actual del proyecto se identifica así:
- Fuente original:
PS_Mexico/TEST_PS_MX_1_limpieza.py,TEST_PS_MX_2_modelado.py,TEST_PS_MX_3_reglas_negocio.py(los TEST de México). - Primer refactor multi-país:
PS_MultiPais/TEST_PS_MP_*.py— generalizaron el código para aceptar el parámetrocode_country. - Versión canónica actual (productiva):
cicd/src/PS_MP_*.py— losPS_MultiPais/TEST_PS_MP_*parametrizados, empaquetados en Docker para ejecutar comoProcessingStepde SageMaker.
Esta cadena de derivación queda registrada acá para que la trazabilidad sea explícita.
Dependencias entre scripts · orden de ejecución
El SM Pipeline ejecuta las etapas en orden secuencial estricto. Cada etapa lee outputs de la anterior.
EventBridge cron por país (L-V, escalonado 10:00→11:00 UTC)
│
▼
Lambda aje-dev-ps-triggerfunction-lambda
│ invoca con event = { code_country: "EC" }
▼
SageMaker Pipeline aje-dev-ps-pipeline-sagemaker
│
├─► Step Limpieza (ProcessingStep, Docker processing)
│ └─ Inputs: S3 (maestro · visitas · ventas · stock) + DynamoDB config
│ └─ Output: CSVs por ruta + parquet
│
├─► Step Modelado (ProcessingStep, Docker spark)
│ └─ Inputs: outputs de Limpieza
│ └─ Output: modelo + recomendaciones top-N
│
└─► Step ReglasNegocio (ProcessingStep, Docker processing)
└─ Inputs: outputs de Modelado + maestro + recurrentes + stock
└─ Output: recomendaciones finales para el área comercial
No hay paralelismo dentro de un país (los steps son secuenciales por dependencia de outputs). El paralelismo es entre países: los 7 schedules de EventBridge están escalonados 10 min entre cada uno para respetar el quota AWS de instancias concurrentes (ml.m5.4xlarge limitado a 4).
Observaciones y riesgos identificados
| # | Hallazgo | Acción de mitigación |
|---|---|---|
| 1 | Múltiples copias del PROD de México (PROD_PS_Mexico.ipynb + PROD_PS_Mexico copy_2026-02-27.ipynb + D_PS_Mexico_2024-*.ipynb × 2) sugieren historial de trabajo no consolidado |
Confirmar en Sesión 1 cuál es la versión vigente que debe respaldar la lógica canónica |
| 2 | El proyecto separado Pedido Estratégico Ecuador (PEs_Ecuador/) está en el mismo repo pero fuera de alcance |
Mantener como referencia. Si AJE quiere extenderlo al pipeline en el futuro, sería una nueva propuesta |
| 3 | Reporting/ contiene scripts de reportes consolidados de los 7 países |
Documentar pero no incluir en el refactor del Nivel 1. Posible alcance Nivel 2 si AJE lo solicita |
| 4 | PS_Econoredes_Ecuador/ es una variante de Ecuador para canal "Econoredes" |
Verificar en Sesión 1 si debe consolidarse con PS_Ecuador o tratarse como país distinto en la config DynamoDB |
| 5 | Hay dos formatos de configuración (PS_PaisesConfig/ y PS_PaisesConfigDynamo/) |
Mantener PS_PaisesConfigDynamo/ como fuente de verdad. La carpeta histórica puede archivarse al cierre del proyecto |