Este repositório contém o projeto completo desenvolvido para o Challenge Sprint - HP, abrangendo desde a coleta de dados (web scraping) até a análise exploratória, rotulagem heurística, uma plataforma de observabilidade e um pipeline completo de Machine Learning para classificação de autenticidade de produtos HP. O projeto está organizado em módulos, cada um com suas dependências e instruções de execução.

O projeto está organizado na seguinte estrutura de pastas:

. (diretório raiz)
├── backend/             # Código do backend (Flask) da plataforma de observabilidade
├── data/                # Datasets CSV (limpos, enriquecidos, mockados)
├── logs/                # Arquivos de log das execuções
├── misc/                # Arquivos diversos (READMEs específicos, todo.md, etc.)
├── notebooks/           # Jupyter Notebooks (IPYNB e HTML) para EDA e ML Pipeline
├── presentations/       # Apresentações (HTML) geradas
├── production_api/      # API de Produção completa (Sprint 3)
│   ├── app/                    # Aplicação Flask principal
│   │   ├── api/               # Endpoints REST
│   │   ├── services/          # Serviços de negócio (ML, scraping, etc.)
│   │   ├── utils/             # Utilitários (database, logging)
│   │   └── models.py          # Modelos de database
│   ├── config/                # Configurações por ambiente
│   ├── tests/                 # Testes unitários e de integração
│   ├── run_api.py             # Servidor principal
│   ├── init_db.py             # Inicialização do database
│   └── requirements.txt       # Dependências da API
├── reports/             # Relatórios (Markdown e PDF)
├── scripts/             # Scripts Python (scrapers, limpeza, EDA, rotulagem, etc.)
├── src/                 # Pipeline de Machine Learning modular (Sprint 3)
│   ├── feature_engineering/    # Engenharia de features
│   ├── preprocessing/          # Pré-processamento de dados
│   ├── models/                 # Treinamento de modelos
│   ├── hyperparameter_optimization/  # Otimização de hiperparâmetros
│   ├── validation/             # Validação e comparação de modelos
│   ├── interpretation/         # Interpretabilidade de modelos
│   ├── persistence/            # Persistência e versionamento
│   └── reporting/              # Geração de relatórios
├── visualizations/      # Visualizações (PNG) geradas pela EDA
└── zips/                # Arquivos ZIP de entregas anteriores

Para rodar qualquer parte deste projeto, você precisará ter o Python 3.x e o Node.js (com pnpm) instalados em seu sistema.

Certifique-se de ter o Python 3.x instalado. É recomendado usar um ambiente virtual para gerenciar as dependências.

python3 -m venv venv_global
source venv_global/bin/activate
pip install --upgrade pip

Para o frontend, você precisará do Node.js e do pnpm (gerenciador de pacotes).

sudo apt install nodejs npm
sudo npm install -g pnpm

O projeto está dividido em três sprints principais:

• Sprint 1: Coleta e Processamento de Dados
• Sprint 2: Análise Exploratória e Plataforma de Observabilidade
• Sprint 3: Pipeline de Machine Learning para Classificação de Autenticidade

Cada módulo do projeto possui suas próprias dependências e instruções de execução. Certifique-se de estar no diretório raiz do projeto antes de executar os comandos.

Descrição: Coleta de dados de produtos HP do Mercado Livre e Americanas.

Dependências:

• selenium
• beautifulsoup4
• pandas
• lxml
• chromium-browser (para Selenium)

Instalação:

pip install selenium beautifulsoup4 pandas lxml
sudo apt-get update
sudo apt-get install -y chromium-browser

Como Rodar:

• scripts/hp_scraper.py (Mercado Livre):

  python3 scripts/hp_scraper.py

  Nota: Este script pode precisar de ajustes nos seletores CSS devido a mudanças frequentes na estrutura do site.

• **scripts/americanas_scraper.py (Americanas - Dados Mockados):

  python3 scripts/americanas_scraper.py

  Nota: O scraper da Americanas foi configurado para usar dados mockados devido à complexidade e instabilidade dos seletores. O script scripts/generate_americanas_mock_data.py pode ser usado para gerar novos dados mockados.

• scripts/generate_demo_data.py (Gerador de Dados Demo):

  python3 scripts/generate_demo_data.py

Descrição: Limpeza, padronização e enriquecimento dos dados coletados.

Dependências:

• pandas

Instalação:

pip install pandas

Como Rodar:

• **scripts/data_cleaning.py (Limpeza e Padronização):

  python3 scripts/data_cleaning.py

• **scripts/data_enrichment.py (Enriquecimento):

  python3 scripts/data_enrichment.py

• **scripts/data_integration.py (Integração de Múltiplas Fontes):

  python3 scripts/data_integration.py

Descrição: Aplicação de critérios heurísticos para classificar produtos como

"original" ou "suspeito/pirata".

Dependências:

• pandas

Instalação:

pip install pandas

Como Rodar:

• **scripts/heuristic_labeling.py (Rotulagem Heurística):

  python3 scripts/heuristic_labeling.py

• **scripts/dataset_generation.py (Geração do Dataset Estruturado):

  python3 scripts/dataset_generation.py

Descrição: Análise exploratória e descritiva dos dados coletados, incluindo visualizações e insights.

Dependências:

• pandas
• numpy
• matplotlib
• seaborn
• nltk
• wordcloud
• jupyter (para abrir e executar o notebook)

Instalação:

pip install pandas numpy matplotlib seaborn nltk wordcloud jupyter
python3 -c "import nltk; nltk.download("punkt", quiet=True); nltk.download("stopwords", quiet=True); nltk.download("rslp", quiet=True)"

Como Rodar:

• notebooks/eda_notebook.ipynb: Para abrir e executar o notebook, navegue até a pasta notebooks/ e inicie o Jupyter Notebook:

  cd notebooks/
  jupyter notebook

  Em seu navegador, abra o arquivo eda_notebook.ipynb.

• **scripts/eda_script.py (Script de EDA - usado para gerar as visualizações no notebook):

  python3 scripts/eda_script.py

Descrição: Aplicação web para visualização e monitoramento dos dados de produtos HP.

Dependências:

• Backend (Flask): Flask, flask-cors, pandas (se usar dados reais, mas aqui está mockado)
• Frontend (React): react, react-dom, vite, tailwindcss, recharts, @radix-ui/react-*, lucide-react

Instalação do Backend:

cd backend/hp_observability_backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Como Rodar o Backend:

cd backend/hp_observability_backend
source venv/bin/activate
python src/main.py

Instalação do Frontend:

cd hp-observability-frontend
pnpm install

Como Rodar o Frontend:

cd hp-observability-frontend
pnpm run dev

Nota: Certifique-se de que o backend esteja rodando antes de iniciar o frontend, pois o frontend consome a API do backend.

Descrição: Pipeline completo de Machine Learning para classificação automática de produtos HP como "original" ou "suspeito/pirata" usando técnicas avançadas de feature engineering, múltiplos algoritmos de ML, otimização de hiperparâmetros e interpretabilidade de modelos. Inclui também uma API de produção completa para deploy e uso em tempo real do sistema de classificação.

O pipeline segue uma arquitetura modular com separação clara de responsabilidades:

Raw Data → Feature Engineering → Preprocessing → Model Training → Hyperparameter Optimization → Validation → Interpretation → Persistence → Reporting

Principais bibliotecas:

• scikit-learn - Algoritmos de ML e utilitários
• pandas, numpy - Manipulação de dados
• matplotlib, seaborn - Visualizações
• joblib - Serialização de modelos
• imbalanced-learn - Técnicas para dados desbalanceados
• reportlab - Geração de relatórios PDF

Instalação:

pip install scikit-learn pandas numpy matplotlib seaborn joblib imbalanced-learn reportlab

# Navegue para o diretório notebooks
cd notebooks/

# Execute o pipeline modular completo
python ml_pipeline_modular.py

# 1. Feature Engineering
from src.feature_engineering import FeatureEngineeringPipeline
pipeline = FeatureEngineeringPipeline()
X, y = pipeline.fit_transform(df)

# 2. Preprocessing
from src.preprocessing import create_complete_preprocessing_pipeline
results = create_complete_preprocessing_pipeline(X, y, imbalance_method='smote')

# 3. Model Training & Optimization
from src.hyperparameter_optimization import optimize_multiple_models
models = ['random_forest', 'svm', 'logistic_regression']
optimization_results = optimize_multiple_models(models, X_train, y_train)

# 4. Model Validation
from src.validation import create_model_comparison_table
comparison = create_model_comparison_table(models_results, cv_results)

# 5. Model Interpretation
from src.interpretation import InterpretationPipeline
interpreter = InterpretationPipeline(feature_names, class_names)
importance = interpreter.analyze_feature_importance(model, X_train, y_train)

# 6. Model Recommendation
from src.reporting import ModelRecommendationSystem
recommender = ModelRecommendationSystem()
recommendation = recommender.recommend_model(models_results, cv_results)

# Execute exemplos específicos
python notebooks/hyperparameter_pipeline_example.py
python notebooks/preprocessing_example.py

# Execute testes para validar funcionamento
python notebooks/test_preprocessing.py
python notebooks/test_hyperparameter_pipeline.py
python notebooks/test_validation.py
python notebooks/test_interpretation.py
python notebooks/test_model_recommendation.py

• Features de Texto: Vetorização TF-IDF de títulos e descrições
• Features Numéricas: Normalização de preços, ratings, contagem de reviews
• Features Categóricas: One-hot encoding para plataformas, tipos de produto
• Features Derivadas: Ratios de preço, métricas de texto, indicadores de palavras-chave
• Análise de Correlação: Remoção automática de features altamente correlacionadas

• Múltiplos Algoritmos: Random Forest, SVM, Logistic Regression, Gradient Boosting
• Validação Cruzada: 5-fold stratified cross-validation
• Balanceamento de Classes: SMOTE e class weighting
• Interface Consistente: API uniforme para todos os modelos

• Seleção Inteligente: Escolha automática entre GridSearchCV e RandomizedSearchCV
• Gestão de Orçamento: Orçamentos configuráveis e limites de tempo
• Otimização Multi-Modelo: Otimização paralela de múltiplos modelos
• Tracking de Progresso: Monitoramento em tempo real

• Métricas Abrangentes: Precision, recall, F1-score, AUC-ROC, accuracy
• Testes Estatísticos: Testes de significância entre performances
• Visualizações: Curvas ROC, matrizes de confusão, heatmaps
• Análise de Overfitting: Detecção automática de overfitting

• Feature Importance: Análise baseada em árvores e permutação
• Explicação de Predições: Explicações individuais com features contribuintes
• Visualizações Interativas: Plots de importância e explicações
• Insights Automáticos: Geração automática de insights de negócio

• Versionamento Automático: Tracking de versões com metadata
• Serialização Completa: Salvamento de pipelines completos
• Validação de Compatibilidade: Verificação de esquemas ao carregar
• Metadata Rica: Métricas de performance, parâmetros, schemas

• Restrições de Negócio: Configuração de requisitos de accuracy, interpretabilidade
• Avaliação de Deploy: Análise multi-critério para produção
• Scoring Inteligente: Combina métricas técnicas com requisitos de negócio
• Relatórios Executivos: Recomendações business-friendly

• Accuracy: >85% no conjunto de teste
• F1-Score: >0.85 para classificação balanceada
• AUC-ROC: >0.90 para forte discriminação
• Interpretabilidade: Explicações claras para decisões de negócio

src/
├── feature_engineering/     # Extração e transformação de features
├── preprocessing/           # Pré-processamento e divisão de dados
├── models/                 # Implementações de treinamento
├── hyperparameter_optimization/  # Otimização automática
├── validation/             # Avaliação e comparação
├── interpretation/         # Explicabilidade
├── persistence/           # Persistência com versionamento
├── reporting/             # Geração de relatórios
└── config.py              # Configurações do pipeline

Nota: Para documentação detalhada do pipeline ML, consulte src/README.md.

Descrição: Sistema completo de produção que integra o pipeline de ML em uma API REST robusta, com scraping automatizado, classificação em tempo real, monitoramento de sistema e interface web para gestão e visualização.

Web Scraping → Database Storage → ML Classification → REST API → Web Interface
     ↓              ↓                    ↓              ↓           ↓
Cron Jobs → Product Storage → Batch Processing → API Endpoints → Dashboard

• ML Service: Carregamento e gestão de modelos treinados
• Classification Service: Classificação de produtos com explicações
• Scraper Service: Coleta automatizada de dados do Mercado Livre
• Batch Processor: Processamento em lote de produtos
• Feature Service: Engenharia de features em tempo real
• Health Service: Monitoramento de saúde do sistema
• Performance Service: Métricas e analytics de performance

• Product: Armazenamento de dados de produtos
• Classification: Resultados de classificação com confiança
• ScrapingJob: Histórico e status de jobs de scraping
• SystemHealth: Métricas de saúde e performance do sistema

• POST /api/classify - Classificação de produto individual
• GET /api/products - Listagem de produtos com filtros
• GET /api/products/{id} - Detalhes de produto específico
• GET /api/health - Status de saúde do sistema
• GET /api/metrics - Métricas de performance

• Environment Management: Configurações por ambiente (dev/prod)
• Database Migration: Scripts de migração e inicialização
• Cron Jobs: Agendamento automático de scraping
• Docker Support: Containerização para deploy

Principais bibliotecas:

• Flask - Framework web
• SQLAlchemy - ORM para database
• Flask-CORS - Suporte a CORS
• APScheduler - Agendamento de tarefas
• psycopg2 - Driver PostgreSQL
• selenium - Web scraping
• scikit-learn - Modelos ML
• pandas, numpy - Processamento de dados

Instalação:

cd production_api/
pip install -r requirements.txt

cd production_api/

# Copie o arquivo de configuração de exemplo
cp config/.env.example config/.env.local

# Edite as configurações conforme necessário
# DATABASE_URL, SECRET_KEY, etc.

# Inicialize o banco de dados
python init_db.py

# Execute migrações (se necessário)
python migrate_db.py

# Modo desenvolvimento
python run_api.py

# Ou com configurações específicas
FLASK_ENV=development python run_api.py

# Configure cron jobs para scraping automático
python setup_cron.py

# Ou execute scraping manual
python run_scraper.py

# Use o script de deploy
python deploy.py

# Ou com Docker (se disponível)
docker-compose up -d

• Endpoint de Classificação: Classifica produtos instantaneamente
• Batch Processing: Processa múltiplos produtos em lote
• Confidence Scoring: Scores de confiança para cada predição
• Explicações Detalhadas: Reasoning por trás de cada classificação

• Cron Jobs: Coleta automática de dados em intervalos regulares
• Error Handling: Recuperação automática de falhas
• Data Validation: Validação e limpeza de dados coletados
• Duplicate Detection: Prevenção de dados duplicados

• Health Checks: Monitoramento contínuo de componentes
• Performance Metrics: Métricas de latência, throughput e accuracy
• System Alerts: Alertas automáticos para problemas
• Usage Analytics: Estatísticas de uso da API

• Product Management: CRUD completo para produtos
• Classification History: Histórico completo de classificações
• Data Export: Exportação de dados em múltiplos formatos
• Backup & Recovery: Sistemas de backup automático

# Classificar um produto
curl -X POST http://localhost:5000/api/classify \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Cartucho HP 664 Original",
    "description": "Cartucho original HP",
    "price": 89.90,
    "seller_name": "HP Store Oficial",
    "rating": 4.8,
    "reviews_count": 150
  }'

# Listar produtos com filtros
curl "http://localhost:5000/api/products?prediction=original&limit=10&page=1"

# Filtrar por confiança
curl "http://localhost:5000/api/products?min_confidence=0.8"

# Status de saúde
curl "http://localhost:5000/api/health"

# Métricas de performance
curl "http://localhost:5000/api/metrics"

cd production_api/tests/

# Execute todos os testes
pytest -v

# Testes específicos
pytest test_ml_service.py -v
pytest test_classification_service.py -v
pytest test_api_routes.py -v

# Testes end-to-end
pytest test_integration.py -v

# Testes de database
pytest test_database_integration.py -v

# Testes de API
pytest test_api_integration.py -v

# Validar estrutura dos testes
python tests/validate_integration_tests.py

# Runner de testes integrado
python tests/test_integration_runner.py

production_api/
├── app/
│   ├── __init__.py              # Factory da aplicação Flask
│   ├── models.py                # Modelos de database
│   ├── api/routes.py            # Endpoints REST
│   ├── services/                # Serviços de negócio
│   └── utils/                   # Utilitários
├── config/
│   ├── config.py                # Configurações por ambiente
│   ├── .env.example             # Template de variáveis
│   └── factory.py               # Factory de configuração
├── tests/
│   ├── test_integration.py      # Testes end-to-end
│   ├── test_api_integration.py  # Testes de API
│   └── conftest.py              # Configuração pytest
├── run_api.py                   # Servidor principal
├── init_db.py                   # Inicialização database
├── setup_cron.py                # Configuração cron jobs
└── requirements.txt             # Dependências

• Latência de Classificação: <200ms por produto
• Throughput: >100 classificações/minuto
• Uptime: >99.5% disponibilidade
• Accuracy: >85% precisão nas classificações
• Scraping Rate: >1000 produtos/hora

Nota: Para documentação detalhada da API, consulte production_api/README.md e production_api/DEPLOYMENT.md.

Para rodar o projeto completo do zero, siga os passos abaixo na ordem:

1. Configuração Inicial do Ambiente: Siga as instruções na seção "Configuração Inicial do Ambiente" para instalar Python, Node.js e pnpm.

2. Web Scraping (Opcional - Use dados mockados para agilizar):

   • Execute python3 scripts/generate_demo_data.py para gerar dados mockados do Mercado Livre.
   • Execute python3 scripts/generate_americanas_mock_data.py para gerar dados mockados da Americanas.

3. Processamento de Dados:

   • Execute python3 scripts/data_cleaning.py.
   • Execute python3 scripts/data_enrichment.py.
   • Execute python3 scripts/data_integration.py.

4. Rotulagem Heurística:

   • Execute python3 scripts/heuristic_labeling.py.
   • Execute python3 scripts/dataset_generation.py.

5. Análise Exploratória de Dados (EDA):

   • Navegue até a pasta notebooks/ e inicie o Jupyter Notebook (jupyter notebook).
   • Abra e execute o eda_notebook.ipynb célula por célula.

6. Plataforma de Observabilidade:

   • Backend: Siga as instruções de instalação e execução do backend (backend/hp_observability_backend).
   • Frontend: Siga as instruções de instalação e execução do frontend (hp-observability-frontend).

7. Pipeline de Machine Learning:

   • Instalação das dependências ML:

     pip install scikit-learn pandas numpy matplotlib seaborn joblib imbalanced-learn reportlab

   • Execução do Pipeline Completo:

     cd notebooks/
     python ml_pipeline_modular.py

   • Ou execute módulos individuais conforme necessário (ver seção Sprint 3 acima)

8. API de Produção:

   • Instalação das dependências da API:

     cd production_api/
     pip install -r requirements.txt

   • Configuração do ambiente:

     cp config/.env.example config/.env.local
     # Edite config/.env.local com suas configurações

   • Inicialização do database:

     python init_db.py

   • Execução da API:

     python run_api.py

     A API estará disponível em http://localhost:5000

   • Configuração de scraping automático (opcional):

     python setup_cron.py

9. Testes e Validação (Opcional mas Recomendado):

   Testes do Pipeline ML:

   python notebooks/test_preprocessing.py
   python notebooks/test_hyperparameter_pipeline.py
   python notebooks/test_validation.py
   python notebooks/test_interpretation.py
   python notebooks/test_model_recommendation.py

   Testes da API de Produção:

   cd production_api/tests/
   pytest -v
   python test_integration_runner.py

Ao final, você terá:

• Dados coletados e processados (Sprint 1)
• Análise exploratória completa com insights e visualizações (Sprint 2)
• Plataforma de observabilidade rodando em http://localhost:5173 (Sprint 2)
• Pipeline de ML completo com modelos treinados, otimizados e prontos para produção (Sprint 3)
• API de produção rodando em http://localhost:5000 com classificação em tempo real (Sprint 3)
• Sistema de scraping automatizado com cron jobs e monitoramento (Sprint 3)
• Relatórios técnicos e executivos com recomendações de modelos (Sprint 3)
• Sistema completo de classificação automática de produtos HP por autenticidade (Sprint 3)

• Coleta automatizada de dados de múltiplas fontes
• Limpeza e padronização de dados
• Rotulagem heurística para classificação inicial

• Análise exploratória abrangente com insights de negócio
• Plataforma web para monitoramento e observabilidade
• Visualizações interativas e dashboards

• Pipeline de ML modular e escalável
• Classificação automática com >85% de accuracy
• Sistema de recomendação inteligente de modelos
• Interpretabilidade e explicabilidade completas
• Relatórios técnicos e executivos automatizados
• API de produção completa com REST endpoints
• Sistema de scraping automatizado com cron jobs
• Monitoramento e health checks em tempo real
• Testes de integração abrangentes (end-to-end, database, API)
• Deploy ready com configurações de produção

• Cobertura de Dados: >1000 produtos coletados e analisados
• Accuracy do Modelo: >85% na classificação de autenticidade
• Tempo de Processamento: <5 minutos para pipeline completo
• Interpretabilidade: Explicações claras para 100% das predições
• Automação: Pipeline totalmente automatizado do dado bruto ao modelo em produção

• Performance da API: <200ms latência por classificação
• Throughput: >100 classificações por minuto
• Disponibilidade: >99.5% uptime
• Scraping Rate: >1000 produtos coletados por hora
• Cobertura de Testes: >90% cobertura de código com testes de integração
• Monitoramento: Health checks e métricas em tempo real
• Escalabilidade: Suporte a processamento em lote e cron jobs automatizados