Credit Card Fraud Detection

Sistema de detecção de fraude em transações de cartão de crédito usando Machine Learning.

Visão Geral

Solução end-to-end para classificação de transações fraudulentas:

• API REST para predição online (Flask)
• Batch Processing para grandes volumes offline
• Pipeline ML reproduzível (scikit-learn)

Problema de Negócio

Dataset altamente desbalanceado (0.17% fraude). Estratégia: priorizar Recall sobre Precision — é mais custoso não detectar fraude do que bloquear transação legítima.

Quando Usar Cada Modo

Cenário	Modo	Motivo
Avaliar uma transação em tempo real	API	Resposta em milissegundos
Processar histórico de transações	Batch	Alto volume, sem urgência
Poucas transações por vez	API	Simplicidade de integração
Milhares/milhões de registros	Batch	Otimizado para memória (chunking)

Predição Instantânea (API)

Use quando: Precisa de resposta imediata para uma ou poucas transações.

# Inicie a API
python -m app.main --port 5000

# Faça uma predição
curl -X POST http://localhost:5000/predict \
  -H "Content-Type: application/json" \
  -d '{"transaction": {...}, "threshold": 0.3}'

Características:

• Latência: ~10-50ms por request
• Modelo carregado em memória (singleton)
• Rate limit: 60 req/min por IP
• Suporta autenticação via API Key

Predição em Lote (Batch)

Use quando: Precisa processar grande volume de transações offline.

# Execute o processamento batch
python -m batch.run_batch \
  --input data/transactions.csv \
  --output data/predictions.csv \
  --model fraud_detector_v1 \
  --threshold 0.3 \
  --chunk-size 10000

Características:

• Processa arquivos CSV de qualquer tamanho
• Chunking para otimizar memória
• Output: CSV com fraud_probability e is_fraud
• Ideal para cron jobs e pipelines de dados

Arquitetura

┌─────────────────────────────────────────────────────────────┐
│                      FRAUD DETECTION                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────┐    ┌─────────────┐    ┌──────────────────┐     │
│  │  DATA   │───▶│  FEATURES   │───▶│     MODELO       │     │
│  │  (CSV)  │    │  PIPELINE   │    │  (RF/LogReg)     │     │
│  └─────────┘    └─────────────┘    └──────────────────┘     │
│                        │                    │               │
│                        ▼                    ▼               │
│               ┌─────────────┐      ┌──────────────┐         │
│               │   BATCH     │      │    API       │         │
│               │  PROCESSOR  │      │   (Flask)    │         │
│               └─────────────┘      └──────────────┘         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Estrutura do Projeto

fraud-detection-mlops/
├── app/                    # API Flask
│   ├── api/                # Rotas, schemas, validadores
│   └── services/           # Lógica de predição
├── ml/                     # Machine Learning
│   ├── data/               # Carregamento de dados
│   ├── features/           # Feature engineering
│   ├── models/             # Treino e avaliação
│   ├── pipelines/          # Pipeline sklearn
│   └── artifacts/          # Modelos salvos
├── batch/                  # Processamento offline
├── tests/                  # Testes automatizados
└── docker/                 # Containerização

Quick Start

Pré-requisitos

• Python 3.11+
• Dataset: data/creditcard.csv (Kaggle Credit Card Fraud Detection)

Instalação

# Clone e entre no diretório
cd fraud-detection-mlops

# Crie ambiente virtual
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate   # Windows

# Instale dependências
pip install -r requirements.txt

Comandos Rápidos (Makefile)

make install     # Instala dependências
make test        # Executa testes com cobertura
make train       # Treina o modelo
make run         # Inicia a API
make clean       # Remove arquivos temporários

Treinar Modelo

python -m ml.models.train --model-type random_forest --model-name fraud_detector_v1

Artefatos salvos em ml/artifacts/:

• fraud_detector_v1.joblib — Pipeline completo
• fraud_detector_v1_metadata.json — Métricas e configuração

Rodar API

python -m app.main --port 5000

Endpoints disponíveis:

Método	Endpoint	Descrição
GET	/	Info da API
GET	/health	Health check
POST	/predict	Predição de fraude

Exemplo de Predição

curl -X POST http://localhost:5000/predict \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": {
      "Time": 0,
      "Amount": 149.62,
      "V1": -1.36, "V2": -0.07, "V3": 2.54, "V4": 1.38,
      "V5": -0.34, "V6": 0.46, "V7": 0.24, "V8": 0.10,
      "V9": 0.36, "V10": 0.09, "V11": -0.55, "V12": -0.62,
      "V13": -0.99, "V14": -0.31, "V15": 1.47, "V16": -0.47,
      "V17": 0.21, "V18": 0.03, "V19": 0.40, "V20": 0.25,
      "V21": -0.02, "V22": 0.28, "V23": -0.11, "V24": 0.07,
      "V25": 0.13, "V26": -0.19, "V27": 0.13, "V28": -0.02
    },
    "threshold": 0.3
  }'

Resposta:

{
  "success": true,
  "prediction": {
    "is_fraud": false,
    "fraud_probability": 0.0023,
    "threshold": 0.3
  }
}

Rodar Batch

python -m batch.run_batch \
  --input data/transactions.csv \
  --output data/predictions.csv \
  --model-name fraud_detector_v1 \
  --threshold 0.3

Executar Testes

pytest tests/ -v

Decisões Técnicas

Threshold 0.3 (não 0.5)

Em fraude, o custo de um Falso Negativo (fraude não detectada) supera o de Falso Positivo (bloqueio indevido). Threshold 0.3 aumenta Recall de ~85% para ~90%+.

class_weight='balanced'

Dataset com 99.83% não-fraude. O parâmetro ajusta pesos inversamente proporcional à frequência das classes, evitando viés para classe majoritária.

Feature Engineering

Feature	Transformação	Justificativa
Time	sin/cos (hora)	Captura padrão cíclico (23h ≈ 0h)
Amount	RobustScaler	Resistente a outliers comuns em fraude
V1-V28	Passthrough	Já são PCA do dataset original

Pipeline sklearn

ColumnTransformer + Pipeline garante que preprocessing seja idêntico em treino, API e batch. Evita data leakage.

Variáveis de Ambiente

Copie .env.example para .env e configure:

cp .env.example .env

Variável	Descrição	Default
FRAUD_API_KEY	API Key para autenticação (opcional)	-
MODEL_NAME	Nome do modelo a carregar	fraud_detector_v1
FLASK_HOST	Host do servidor	0.0.0.0
FLASK_PORT	Porta do servidor	5000
FLASK_DEBUG	Modo debug	False

Segurança: Se FRAUD_API_KEY estiver configurada, requests para /predict devem incluir header X-API-Key.

Docker

Build

docker build -f docker/Dockerfile -t fraud-detection-api .

Run

docker run -p 5000:5000 \
  -v ./ml/artifacts:/app/ml/artifacts:ro \
  fraud-detection-api

Docker Compose

docker-compose -f docker/docker-compose.yml up --build

Stack

• Python 3.11
• Flask 3.0 — API REST
• scikit-learn 1.3 — Pipeline ML
• pandas/numpy — Manipulação de dados
• pytest — Testes
• Docker — Containerização

Limitações Conhecidas e Decisões Arquiteturais

Modelo no Filesystem (Decisão Consciente)

O modelo é carregado de ml/artifacts/ no filesystem. Para escalar horizontalmente:

Opção 1 — Volume compartilhado (atual):

docker run -v /shared/models:/app/ml/artifacts:ro fraud-detection-api

Opção 2 — Model Registry externo:

• MLflow, S3, GCS para centralizar artefatos
• Requer modificação em load_pipeline()

Trade-off: Simplicidade vs Escalabilidade. Para MVP/POC, filesystem + volume é suficiente.

Outras Limitações

1. Sem monitoring — Adicionar Prometheus/Grafana para métricas de latência e drift

Licença

MIT