Sistema de Detecção de Fraudes em Cartões de Crédito

Este projeto implementa um sistema completo de machine learning para detectar fraudes em transações de cartões de crédito usando o dataset do Kaggle.

📊 Dataset

• Fonte: Credit Card Fraud Detection - Kaggle
• Tamanho: 284,807 transações
• Features: 29 variáveis (V1-V28 + Amount)
• Classes:
  • Normal: 284,315 (99.83%)
  • Fraude: 492 (0.17%)
• Desbalanceamento: 577.9:1

🚀 Características do Projeto

Análise Exploratória de Dados (EDA)

• Distribuição das classes
• Análise temporal das transações
• Análise das features PCA (V1-V28)
• Padrões de fraude identificados
• Visualizações interativas

Pré-processamento

• Scaling: RobustScaler (robusto a outliers)
• Balanceamento: SMOTE (10% de fraudes)
• Divisão: 80% treino / 20% teste (estratificada)

Modelos Implementados

1. Random Forest (Melhor) - F1: 0.7980, AUC: 0.9592
2. Extra Trees - F1: 0.7905, AUC: 0.9801
3. Gradient Boosting - F1: 0.7421, AUC: 0.9770
4. Decision Tree - F1: 0.3396, AUC: 0.9107
5. Logistic Regression - F1: 0.1082, AUC: 0.9688

Otimização

• Grid Search com validação cruzada
• Métricas focadas em F1-Score
• Hiperparâmetros otimizados

🎮 CLI Interativo

O projeto inclui um CLI (Command Line Interface) para testar o modelo facilmente:

Características do CLI:

• Modo Interativo: Interface amigável para entrada de dados
• Modo Linha de Comando: Para testes rápidos e automação
• Apenas 7 Parâmetros: Foco nas features mais importantes
• Resultados Detalhados: Probabilidade, nível de risco e recomendações
• Formatação Amigável: Interface colorida e fácil de entender

Parâmetros Necessários:

• --amount: Valor da transação em reais
• --v4, --v10, --v11, --v12, --v14, --v17: Features mais importantes

Exemplos de Uso:

# Transação normal
poetry run python cli_fraud_detector.py --amount 50.00 --v4 0.5 --v10 -0.3 --v11 0.2 --v12 -0.1 --v14 0.4 --v17 -0.2

# Transação suspeita
poetry run python cli_fraud_detector.py --amount 1000.00 --v4 2.5 --v10 -2.1 --v11 1.8 --v12 -2.3 --v14 1.5 --v17 -1.2

# Ver documentação completa
cat docs/cli.md

📁 Estrutura do Projeto

creditcard_fraud/
├── src/                        # Código fonte
│   ├── eda.py                  # Análise exploratória
│   ├── fraud_detection_fast.py # Pipeline principal otimizado
│   ├── demo_modelo.py          # Demonstração do modelo
│   └── cli_fraud_detector.py   # CLI interativo
├── models/                     # Modelos treinados
│   └── best_fraud_model_fast.pkl
├── data/                       # Dados
│   └── creditcard.csv          # Dataset original
├── docs/                       # Documentação
│   ├── cli.md                  # Documentação do CLI
│   ├── analise_graficos.md     # Análise dos gráficos
│   ├── processo_implementacao.md # Processo de desenvolvimento
│   └── *.png                   # Gráficos de análise
├── tests/                      # Testes
│   └── test_fraud_cases.py     # Testes com casos reais
├── setup.py                    # Script de configuração
├── .gitignore                  # Arquivos ignorados
├── pyproject.toml              # Dependências Poetry
└── README.md                   # Este arquivo

🛠️ Instalação e Uso

Pré-requisitos

• Python 3.12+
• Poetry

Instalação

# Instalar dependências
poetry install --no-root

# Ativar ambiente virtual
poetry shell

Setup Rápido

# Verificar configuração do projeto
python setup.py

# Instalar dependências
poetry install --no-root

Execução

1. Análise Exploratória

poetry run python src/eda.py

2. Treinamento do Modelo

poetry run python src/fraud_detection_fast.py

3. Demonstração

poetry run python src/demo_modelo.py

4. CLI Interativo (NOVO!)

# Modo interativo
poetry run python src/cli_fraud_detector.py

# Modo linha de comando
poetry run python src/cli_fraud_detector.py --amount 100.50 --v4 1.2 --v10 -0.8 --v11 0.5 --v12 -1.1 --v14 0.3 --v17 -0.2

# Ver documentação completa
cat docs/cli.md

📚 Documentação

Guias Disponíveis

• docs/cli.md: Guia completo do CLI interativo
• docs/analise_graficos.md: Análise detalhada dos gráficos gerados
• docs/processo_implementacao.md: Processo completo de desenvolvimento

Comandos de Documentação

# Ver guia do CLI
cat docs/cli.md

# Ver análise dos gráficos
cat docs/analise_graficos.md

# Ver processo de implementação
cat docs/processo_implementacao.md

# Ver documentação principal
cat README.md

📈 Resultados

Performance do Melhor Modelo (Random Forest)

• Acurácia: 99.93%
• Precisão: 77.14%
• Recall: 82.65%
• F1-Score: 79.80%
• AUC-ROC: 95.92%
• AUC-PR: 85.77%

Features Mais Importantes

1. V10 (14.80%)
2. V14 (13.58%)
3. V4 (13.02%)
4. V12 (10.29%)
5. V11 (10.20%)

🎯 Métricas de Avaliação

O projeto utiliza métricas apropriadas para dados desbalanceados:

• F1-Score: Balanceamento entre precisão e recall
• AUC-ROC: Capacidade de distinguir classes
• AUC-PR: Performance em dados desbalanceados
• Matriz de Confusão: Análise detalhada dos erros

📊 Visualizações Geradas

• class_distribution.png: Distribuição das classes
• time_amount_analysis.png: Análise temporal e de valores
• pca_features_analysis.png: Análise das features PCA
• fraud_patterns_analysis.png: Padrões de fraude
• fast_model_evaluation.png: Avaliação dos modelos
• feature_importance.png: Importância das features

🔧 Tecnologias Utilizadas

• Python 3.12+
• Pandas: Manipulação de dados
• NumPy: Computação numérica
• Scikit-learn: Machine learning
• Imbalanced-learn: Balanceamento de classes
• Matplotlib/Seaborn: Visualizações
• Poetry: Gerenciamento de dependências

📝 Conclusões

O sistema desenvolvido demonstra excelente capacidade de detecção de fraudes:

1. Alta Performance: F1-Score de 79.80% indica bom balanceamento entre precisão e recall
2. Baixa Taxa de Falsos Positivos: Precisão de 77.14% reduz alertas desnecessários
3. Boa Cobertura: Recall de 82.65% detecta a maioria das fraudes reais
4. Robustez: AUC-ROC de 95.92% indica excelente capacidade de classificação

O modelo está pronto para uso em produção e pode ser facilmente integrado a sistemas de monitoramento de transações em tempo real.

👨‍💻 Autor

Jesus Vieira - [email protected]

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

Resumo da Licença MIT:

• ✅ Uso comercial: Permitido
• ✅ Modificação: Permitido
• ✅ Distribuição: Permitido
• ✅ Uso privado: Permitido
• ✅ Código aberto: Sim

Única condição: Incluir o aviso de copyright e a licença em todas as cópias ou partes substanciais do software.