Jumcorrealo

.gitignore

@@ -3,3 +3,5 @@
 env_vars*
 credentials*
 **/build/*
+venv
+*.xlsx

.ipynb_checkpoints/README-checkpoint.md

@@ -0,0 +1,10 @@
+# Team Data Science Project Template
+
+Esta plantilla es una implementación de la plantilla de proyecto de Team Data Science Process que actualmente se utiliza en el "Programa de Formación en Machine Learning y Data Science" en la Universidad Nacional de Colombia.
+
+Esta plantilla proporciona las siguientes carpetas y archivos:
+
+* `src`: acá debe ir el código o implementación del proyecto en Python.
+* `docs`: en esta carpeta se encuentran las plantillas de los documentos definidos en la metodología.
+* `scripts`: esta carpeta debe contener los scripts/notebooks que se ejecutarán.
+* `pyproject.toml`: archivo de definición del proyecto en Python.

.spyproject/config/backups/codestyle.ini.bak

@@ -0,0 +1,8 @@
+[codestyle]
+indentation = True
+edge_line = True
+edge_line_columns = 79
+
+[main]
+version = 0.2.0
+

.spyproject/config/backups/encoding.ini.bak

@@ -0,0 +1,6 @@
+[encoding]
+text_encoding = utf-8
+
+[main]
+version = 0.2.0
+

.spyproject/config/backups/vcs.ini.bak

@@ -0,0 +1,7 @@
+[vcs]
+use_version_control = False
+version_control_system = 
+
+[main]
+version = 0.2.0
+

.spyproject/config/backups/workspace.ini.bak

@@ -0,0 +1,12 @@
+[workspace]
+restore_data_on_startup = True
+save_data_on_exit = True
+save_history = True
+save_non_project_files = False
+project_type = 'empty-project-type'
+recent_files = ['scripts\\eda\\functions.py', 'main.py', 'scripts\\data_acquisition\\api_reader.py', 'scripts\\training\\trainingText.py', 'src\\comparative_analysis\\models\\models.py']
+
+[main]
+version = 0.2.0
+recent_files = []
+

.spyproject/config/codestyle.ini

@@ -0,0 +1,8 @@
+[codestyle]
+indentation = True
+edge_line = True
+edge_line_columns = 79
+
+[main]
+version = 0.2.0
+

.spyproject/config/defaults/defaults-codestyle-0.2.0.ini

@@ -0,0 +1,5 @@
+[codestyle]
+indentation = True
+edge_line = True
+edge_line_columns = 79
+

.spyproject/config/defaults/defaults-encoding-0.2.0.ini

@@ -0,0 +1,3 @@
+[encoding]
+text_encoding = utf-8
+

.spyproject/config/defaults/defaults-vcs-0.2.0.ini

@@ -0,0 +1,4 @@
+[vcs]
+use_version_control = False
+version_control_system = 
+

.spyproject/config/defaults/defaults-workspace-0.2.0.ini

@@ -0,0 +1,6 @@
+[workspace]
+restore_data_on_startup = True
+save_data_on_exit = True
+save_history = True
+save_non_project_files = False
+

.spyproject/config/encoding.ini

@@ -0,0 +1,6 @@
+[encoding]
+text_encoding = utf-8
+
+[main]
+version = 0.2.0
+

.spyproject/config/vcs.ini

@@ -0,0 +1,7 @@
+[vcs]
+use_version_control = False
+version_control_system = 
+
+[main]
+version = 0.2.0
+

.spyproject/config/workspace.ini

@@ -0,0 +1,12 @@
+[workspace]
+restore_data_on_startup = True
+save_data_on_exit = True
+save_history = True
+save_non_project_files = False
+project_type = 'empty-project-type'
+recent_files = ['scripts\\eda\\functions.py', 'main.py', 'scripts\\data_acquisition\\api_reader.py', 'scripts\\training\\trainingText.py', 'src\\comparative_analysis\\models\\models.py', 'src\\comparative_analysis\\models\\utilities\\utilities.py', 'src\\comparative_analysis\\preprocessing\\main.py', 'src\\comparative_analysis\\preprocessing\\functions\\model_inference.py']
+
+[main]
+version = 0.2.0
+recent_files = []
+

docs/acceptance/exit_report.md

@@ -2,31 +2,65 @@
 
 ## Resumen Ejecutivo
 
-Este informe describe los resultados del proyecto de machine learning y presenta los principales logros y lecciones aprendidas durante el proceso.
+Este informe describe los resultados del proyecto de machine learning y presenta los principales logros y lecciones aprendidas durante el proceso. A lo largo del ciclo de vida del proyecto, se aplicó una metodología híbrida basada en CRISP-DM y la gestión ágil de SCRUM, que permitió estructurar las tareas técnicas y facilitar la colaboración entre los miembros del equipo. 
+
+El objetivo primordial fue el desarrollo de un análisis comparativo de calzado deportivo para running, abarcando la extracción, limpieza y transformación de datos provenientes de diferentes marcas y tiendas (Adidas, Nike y Nation Runner), su posterior modelado y la implementación de un modelo de recomendación basado en similitud semántica.
 
 ## Resultados del proyecto
 
-- Resumen de los entregables y logros alcanzados en cada etapa del proyecto.
-- Evaluación del modelo final y comparación con el modelo base.
-- Descripción de los resultados y su relevancia para el negocio.
+- **Resumen de los entregables y logros alcanzados en cada etapa del proyecto**  
+  1. **Entendimiento del Negocio**: Se definió el alcance y los objetivos, estableciendo como meta la creación de un análisis comparativo de productos de running a partir de descripciones textuales, utilizando técnicas de embeddings para lograr mayor precisión semántica.  
+  2. **Entendimiento de los Datos**: Se recopilaron datos mediante scraping de tres fuentes (Adidas, Nike y Nation Runner), dispuestos en una API conectada a Firebase, y finalmente se consolidaron en archivos CSV para su posterior manipulación.  
+  3. **Preparación de los Datos**: Se realizó etiquetado con la ayuda de un LLM, normalización de campos (especialmente precios), y transformación de textos en representaciones vectoriales (embeddings).  
+  4. **Modelado**: Se implementó un primer modelo baseline de clustering (K-Means) para segmentar productos de Adidas según características como peso, drop, precio y tecnologías. Posteriormente, se exploraron otros algoritmos de clustering (Agglomerative, DBSCAN y HDBSCAN) y se entrenó una red neuronal para asignar productos de  Decathlon a los clusters previamente establecidos.  
+  5. **Evaluación y Despliegue**: Se midió la calidad del clustering con métricas de evaluación como Silhouette Score y Davies-Bouldin Score. Aunque los valores no fueron óptimos (-0.107 en Silhouette y ~3.78 en Davies-Bouldin), sí permitieron establecer una línea base para futuros refinamientos. El despliegue contempló la creación de un pipeline reproducible capaz de actualizar los resultados conforme se disponga de datos nuevos.  
+
+- **Evaluación del modelo final y comparación con el modelo base**  
+  El modelo baseline de clustering (K-Means) presentaba un Silhouette Score negativo y un Davies-Bouldin Score relativamente alto, evidenciando una segmentación difusa de los productos. El modelo final, que incluyó mejoras en la selección de variables y la utilización de embeddings más avanzados para el preprocesamiento, mostró ligeras mejoras en la interpretación y clasificación de productos. Sin embargo, las métricas de evaluación aún indican oportunidades de refinamiento para capturar mejor la similitud real entre los productos de calzado deportivo.
+
+- **Descripción de los resultados y su relevancia para el negocio**  
+  A pesar de que las métricas cuantitativas no alcanzaron los valores deseados, se consiguieron los siguientes avances relevantes:
+  - Se estableció un proceso de comparación de productos que facilita la detección de patrones en atributos clave (materiales, tecnologías, precios, peso, etc.).  
+  - Se generó una estructura de datos y un pipeline reproducible, lo que sienta las bases para iteraciones futuras que mejoren la precisión y la utilidad del sistema de recomendación.  
+  - El equipo directivo y comercial dispone ahora de un modelo básico para comprender la distribución y características principales de su catálogo, así como la comparativa con la competencia.
+
+![nuevoProceso (1)](https://github.com/user-attachments/assets/558ff02f-750a-4898-ac6c-9682f701cce0)
 
 ## Lecciones aprendidas
 
-- Identificación de los principales desafíos y obstáculos encontrados durante el proyecto.
-- Lecciones aprendidas en relación al manejo de los datos, el modelamiento y la implementación del modelo.
-- Recomendaciones para futuros proyectos de machine learning.
+- **Identificación de los principales desafíos y obstáculos**  
+  - La calidad e inconsistencia de los datos (valores faltantes o con formatos heterogéneos) representó el principal reto para la normalización y preprocesamiento.  
+  - El uso de descripciones textuales de productos exigió un enfoque especializado (embeddings) para capturar la semántica y evitar la pérdida de información relevante.  
+  - La implementación de un modelo híbrido (LLM + algoritmos de clustering) requiere asegurar la coherencia entre las variables categóricas y numéricas, lo que implicaría un trabajo adicional de mapeo y unificación de criterios.  
+
+- **Lecciones aprendidas en relación al manejo de los datos, el modelamiento y la implementación**  
+  - Un pipeline reproducible, desde el scraping y la limpieza de datos hasta la aplicación de técnicas de modelado, resulta esencial para escalar y mantener el proyecto en el largo plazo.  
+  - Utilizar un LLM para normalizar descripciones textuales puede aportar gran valor, pero se debe contar con supervisión y validaciones adicionales para evitar etiquetados inconsistentes o la propagación de errores semánticos.  
+  - La selección de características y la ingeniería de atributos (feature engineering) juega un papel crítico en el desempeño del modelo. Es vital evaluar periódicamente la relevancia de cada variable.  
+
+- **Recomendaciones para futuros proyectos de machine learning**  
+  - Adoptar estrategias de validación de datos más exhaustivas desde el inicio, asegurando la calidad y consistencia de la información.  
+  - Explorar algoritmos de clustering más adecuados a la naturaleza de los datos, como HDBSCAN, que no requiere especificar de antemano el número de clusters y puede manejar clusters de forma más orgánica.  
+  - Considerar la integración con herramientas de visualización más interactivas (como dashboards) para que el equipo de negocio pueda monitorear y ajustar el modelo de forma continua.
 
 ## Impacto del proyecto
 
-- Descripción del impacto del modelo en el negocio o en la industria.
-- Identificación de las áreas de mejora y oportunidades de desarrollo futuras.
+- **Descripción del impacto del modelo en el negocio o en la industria**  
+  - El modelo de recomendación ofrece una vista preliminar de cómo se agrupan los productos de calzado deportivo, favoreciendo la identificación de nichos de mercado y oportunidades de diferenciación frente a competidores.  
+  - Permite a las áreas comercial y de mercadeo obtener insights rápidos sobre precios, tecnologías y composición de los productos, lo que impulsa decisiones informadas y el desarrollo de nuevas estrategias de posicionamiento.  
 
-## Conclusiones
+- **Identificación de las áreas de mejora y oportunidades de desarrollo futuras**  
+  - Se abre la posibilidad de complementar el modelo con datos de otras marcas no incluidas inicialmente (por ejemplo, Puma o Reebok), ampliando la comparativa y enriqueciendo la visión global del mercado.  
+  - Incluir información de ventas, reseñas de clientes o ratings para correlacionar la efectividad de ciertos atributos del calzado con el desempeño comercial.  
+  - Desarrollar dashboards interactivos y visualizaciones avanzadas que faciliten la interpretación y uso de los resultados por parte de los equipos de negocio y stakeholders.
 
-- Resumen de los resultados y principales logros del proyecto.
-- Conclusiones finales y recomendaciones para futuros proyectos.
+## Conclusiones
 
-## Agradecimientos
+- **Resumen de los resultados y principales logros del proyecto**  
+  - Se logró crear un pipeline integral, desde la extracción de datos con web scraping hasta la generación de clusters de productos, con un primer prototipo de recomendación basado en similitud semántica.  
+  - A pesar de que las métricas de calidad de clustering no fueron óptimas, el proceso sienta las bases para una mejora continua y demuestra el valor de la combinación entre técnicas de embeddings y métodos de clustering/segmentación.  
 
-- Agradecimientos al equipo de trabajo y a los colaboradores que hicieron posible este proyecto.
-- Agradecimientos especiales a los patrocinadores y financiadores del proyecto.
+- **Conclusiones finales y recomendaciones para futuros proyectos**  
+  - El uso de metodologías ágiles y la estructura de CRISP-DM propiciaron un orden claro en la ejecución y un enfoque iterativo para el desarrollo del proyecto.  
+  - Para elevar el valor práctico del modelo, se recomienda profundizar en el perfeccionamiento de las representaciones vectoriales, la selección de algoritmos de clustering más robustos y la incorporación de más variables relevantes (como reseñas de usuarios).  
+  - La escalabilidad del sistema se beneficiaría de un monitoreo periódico de la calidad de datos y la reentrenamiento automático del modelo al integrarse nuevos productos o marcas.

docs/business_understanding/.ipynb_checkpoints/project_charter-checkpoint.md

@@ -0,0 +1,76 @@
+# Project Charter - Entendimiento del Negocio
+
+## Nombre del Proyecto
+
+Análisis comparativo de productos de Running entre Nike, Adidas y Nation Runner
+
+## Objetivo del Proyecto
+
+Desarrollar una herramienta computacional que permita realizar un análisis comparativo de zapatos para running, utilizando datos obtenidos de varias tiendas retail mediante técnicas de procesamiento de lenguaje natural y preprocesamiento de datos, incluyendo el uso de Grandes Modelos de Lenguaje (LLM, por sus siglas en inglés).
+
+## Alcance del Proyecto
+
+El alcance del proyecto consiste en construir un modelo de recomendación basado en embeddings, capaz de generar recomendaciones basadas en la similitud de atributos de calzado deportivo para running, alineados con las necesidades del cliente.
+
+Se propone el uso de embeddings debido a que los datos disponibles consisten en descripciones textuales de las características de diferentes tipos de calzado deportivo. Se busca aplicar técnicas de embeddings utilizando modelos LLM, con el objetivo de mejorar la precisión semántica basada en similitud contextual.
+
+### Incluye:
+
+- Datos de Adidas, Nike y Nation Runner, obtenidos mediante un scraper con corte de datos a mediados de noviembre.
+- Un dataset organizado y etiquetado con modelos comparados.
+- Un modelo que permita realizar análisis comparativos de productos de forma automática y frecuente, con información actualizada sobre los movimientos de mercado de las marcas analizadas.
+
+### Excluye:
+
+- La comparación de productos de marcas no incluidas en el análisis inicial (por ejemplo, Puma o Reebok).
+- El desarrollo de visualizaciones avanzadas, como gráficos interactivos o dashboards personalizados, que no estén especificados como requisitos del proyecto.
+
+## Metodología
+
+Se utilizarán las metodologías CRISP-DM y SCRUM para llevar a cabo el proyecto.
+
+## Cronograma
+
+| Etapa                                    | Duración Estimada | Fechas                          |
+|-----------------------------------------|-------------------|---------------------------------|
+| Entendimiento del negocio y carga de datos | 2 semanas         | Del 13 de noviembre al 28 de noviembre |
+| Preprocesamiento y análisis exploratorio | 1 semana          | Del 29 de noviembre al 5 de diciembre |
+| Modelamiento y extracción de características | 1 semana          | Del 5 de diciembre al 12 de diciembre |
+| Despliegue                               | 1 semana          | Del 13 de diciembre al 19 de diciembre |
+| Evaluación y entrega final               | 1 semana          | Del 19 de diciembre al 21 de diciembre |
+
+## Equipo del Proyecto
+
+- Daniel Galvis CC 1010038257 [email protected]
+- Juan Correa CC 1013653882 [email protected]
+- Asdrúbal Zácipa Corredor CC 79139929 [email protected]
+
+## Presupuesto
+
+Aunque no se cuenta con financiamiento externo, se estimaron los costos básicos relacionados con el desarrollo del proyecto, considerando el uso de recursos personales como luz, internet y equipos de cómputo. A continuación, se detalla el presupuesto:
+
+| Concepto                     | Costo Mensual (COP) | Proporción por Persona (COP) | Duración (meses) | Total (COP) |
+|------------------------------|---------------------|------------------------------|------------------|-------------|
+| Servicio de luz              | 100,000            | 33,333                       | 2                | 200,000     |
+| Servicio de internet         | 150,000            | 50,000                       | 2                | 300,000     |
+| Uso de equipos personales    | 200,000            | 66,667                       | 2                | 400,000     |
+| Reserva para emergencias     | -                  | -                            | -                | 100,000     |
+| **Total**                    | -                  | -                            | -                | **1,000,000** |
+
+### Detalles:
+- **Servicio de luz:** Incluye el costo estimado del consumo eléctrico asociado al trabajo en el proyecto.
+- **Servicio de internet:** Cubre el acceso a internet necesario para reuniones virtuales, investigación y uso de herramientas online.
+- **Uso de equipos personales:** Considera el desgaste de hardware y el consumo eléctrico de los equipos utilizados durante el desarrollo.
+- **Reserva para emergencias:** Monto adicional para imprevistos, como la reparación de equipos o la adquisición de software adicional.
+
+## Stakeholders
+
+- Dirección comercial de una empresa deportiva.
+- Equipo laboral interno interesado en la automatización del análisis comparativo de productos deportivos.
+- Consumidores finales que podrían beneficiarse indirectamente de las recomendaciones generadas por el modelo.
+
+## Aprobaciones
+
+- [Nombre y cargo del aprobador del proyecto]
+- [Firma del aprobador]
+- [Fecha de aprobación]