🏦 Agente de Risco IA (Agent Risk AI) — ML + MCP Server

Agente de Risco IA: Seu analista autônomo de inteligência e risco de crédito via MCP. Um modelo de previsão de inadimplência de cartão de crédito, treinado com rigor metodológico (CV estratificada, tuning bayesiano com Optuna, threshold otimizado, explicabilidade via SHAP) e exposto como servidor MCP — consultável diretamente por Claude Desktop/Code e agentes de IA em linguagem natural.

📌 Por que este projeto é diferente de "só treinar um modelo"

A maioria dos projetos de portfólio para de treinar o modelo e mostrar um .ipynb com métricas. Este vai um passo além: o modelo é encapsulado em um servidor MCP (Model Context Protocol) com 6 ferramentas de negócio, o que significa que qualquer LLM host compatível (Claude Desktop, Claude Code) pode consultar o modelo em linguagem natural, sem escrever código:

🗣️ "Qual o risco de default deste cliente: idade 46, renda R$107.934, score de crédito 544, 2 inadimplências anteriores?" 🤖 → chama predict_default → responde com probabilidade, classe e explicação SHAP.

Isso é exatamente o padrão que está emergindo em times de risco/dados que querem colocar modelos de produção "na conversa", não atrás de um dashboard estático.

Related MCP server: CreddyMCP

🗂️ O problema de negócio

Dataset de 45.528 clientes de cartão de crédito com variáveis demográficas, de renda e de comportamento de crédito. Alvo: credit_card_default (binário), com desbalanceamento real de 8,1% de inadimplência — cenário típico de risco de crédito, onde acurácia ingênua é uma métrica enganosa.

🏗️ Como o Sistema Funciona (Arquitetura Simples)

O projeto transforma dados brutos de crédito em decisões acionáveis e auditáveis consumidas por agentes de IA através de 4 etapas integradas:

flowchart LR
    A["📁 1. Dados Brutos<br/><b>train.csv / test.csv</b>"] --> B["🧹 2. Limpeza & Features<br/><b>DTI, Limite, Flags</b>"]
    B --> C["🤖 3. Cérebro Preditivo<br/><b>XGBoost + Optuna + SHAP</b>"]
    C --> D["🔌 4. Servidor MCP<br/><b>6 Ferramentas de Negócio</b>"]
    D --> E["💬 5. Agente de IA<br/><b>Claude / Cursor / LLMs</b>"]

O Fluxo em 4 Passos:

1. 📁 1. Tratamento & Inteligência Financeira (data_processing.py / feature_engineering.py)

   • Remove dados sensíveis (PII) e trata anomalias do dataset (como o sentinela de aposentados).

   • Cria indicadores financeiros reais: Debt-to-Income (DTI), utilização de limite e renda per capita.

2. 🤖 2. Pipeline de Machine Learning (pipeline.py / train.py)

   • Executa transformações (imputação, one-hot encoding e escala) de forma estanque (sem vazamento de dados).

   • Treina e ajusta o XGBoost via Optuna (25 trials) em validação cruzada 5-fold, calibrando o limiar de decisão ótimo ($F_1 = 0,875$).

3. 🧠 3. Explicabilidade & Auditoria (inference.py / evaluate.py)

   • Persiste o modelo vencedor e o SHAP TreeExplainer para decompor exatamente quais variáveis aumentam ou reduzem o risco de cada cliente em tempo real.

4. 🔌 4. Camada Agêntica MCP (mcp_server/server.py)

   • Expõe 6 ferramentas prontas para que qualquer assistente ou agente de IA (Claude Desktop, Claude Code, etc.) possa consultar o modelo, simular cenários e avaliar portfólios inteiros em linguagem natural.

🔬 Engenharia de features orientada a domínio

Em vez de "jogar tudo no XGBoost", cada feature derivada tem uma justificativa de risco de crédito explícita:

🧪 Metodologia e rigor estatístico

• Winsorização aprendida apenas no treino (percentil 99,5%) e reaplicada no teste/holdout — sem vazamento de dados.

• Pipeline sklearn único (ColumnTransformer + modelo) — imputação e encoding são recalculados a cada fold da validação cruzada, não uma vez só no dataset inteiro (erro comum que infla métricas artificialmente).

• Métrica de seleção: PR-AUC (Average Precision), não ROC-AUC nem acurácia — a escolha correta para 8% de prevalência da classe positiva.

• Holdout de 15% nunca visto durante o tuning do Optuna — as métricas finais abaixo são de generalização real, não de overfitting ao processo de busca.

• Threshold de decisão recalibrado maximizando F1 na curva precisão-recall do holdout (0,875), em vez de usar 0,5 às cegas — essencial quando a classe positiva é rara.

• Explicabilidade via SHAP TreeExplainer — cada predição do servidor MCP pode ser auditada fator a fator (relevante para conformidade regulatória de crédito).

📊 Resultados e Métricas de Performance

Todas as métricas abaixo foram calculadas no conjunto de holdout (6.830 clientes), completamente isolado durante a busca de hiperparâmetros pelo Optuna:

1. Comparativo de Modelos (Validação Cruzada Estratificada 5-Fold)

2. Métricas de Performance no Holdout (Modelo Campeão)

3. Matriz de Confusão Detalhada no Holdout

4. Hiperparâmetros Vencedores (Optuna — 25 Trials)

{
  "n_estimators": 500,
  "max_depth": 4,
  "learning_rate": 0.0121,
  "subsample": 0.7244,
  "colsample_bytree": 0.7301,
  "min_child_weight": 8,
  "gamma": 3.1878,
  "reg_lambda": 3.5388,
  "reg_alpha": 0.0774,
  "scale_pos_weight": 11.3164
}

5. Top 10 Fatores de Risco Auditáveis (Importância Média $|\text{SHAP}|$)

📈 Artefatos Visuais em reports/figures/:

• roc_curve.png — Curva ROC com baseline aleatório.

• precision_recall_curve.png — Curva Precisão-Recall comparada à prevalência base.

• confusion_matrix.png — Matriz de confusão no threshold ótimo.

• shap_summary.png — Beeswarm summary plot de explicabilidade global.

🔒 Todas as métricas acima são reprodutíveis e ficam salvas no metadado de auditoria em models/model_metadata.json.

💡 Guia de Interpretação dos Resultados (Para Leigos e Negócios)

Para facilitar a comunicação entre cientistas de dados, analistas de crédito e diretores não-técnicos, cada saída do sistema possui um significado de negócio direto:

1. 📈 Probabilidade de Default (PD) & Faixas de Ação

• O que é: A probabilidade estimada (de 0% a 100%) de o cliente atrasar o pagamento da fatura em mais de 90 dias nos meses seguintes.

• Como agir com base na faixa:

  • 🟢 MUITO_BAIXO (< 5%) e BAIXO (5% a 15%): Concessão de crédito e aumento de limite recomendados de forma automática com taxas competitivas.

  • 🟡 MODERADO (15% a 35%): Cliente limítrofe. Recomendado limite inicial conservador ou solicitação de comprovação de renda.

  • 🔴 ALTO (35% a 60%) e MUITO_ALTO (≥ 60%): Risco elevado de inadimplência. Recomendada recusa de proposta ou exigência de avalistas/garantias reais.

2. 📊 Como Ler o Gráfico de Explicabilidade SHAP

• 🔴 Barras para a DIREITA (Contribuição Positiva): Fatores cadastrais ou comportamentais que puxam o risco para CIMA (ex: score baixo, uso excessivo do limite rotativo, inadimplência prévia).

• 🟢 Barras para a ESQUERDA (Contribuição Negativa): Fatores saudáveis que protegem o cliente e puxam o risco para BAIXO (ex: estabilidade de anos no emprego, alta renda, score alto).

• 📏 Comprimento da Barra: Quanto maior a barra, mais decisiva essa variável foi para o veredito final da IA.

3. 📉 O que é a Simulação What-If?

• Permite simular o impacto de mudanças em regras ou orientar clientes negados. Por exemplo: "Se você reduzir a utilização do seu limite de 73% para 30%, seu risco cairá de 68% para 22%, permitindo a aprovação do seu cartão."

4. 💰 Exposição Total e Perda Esperada da Carteira

• Exposição Total: O volume financeiro total que a instituição colocou em jogo (soma dos limites de crédito concedidos).

• Perda Esperada ($PD \times \text{Exposição}$): O valor em Reais que a instituição projeta perder estatisticamente por inadimplência se nenhuma ação for tomada.

• Taxa de Perda (%): Base direta para a Provisão para Devedores Duvidosos (PDD / IFRS 9).

🔌 O servidor MCP — 6 ferramentas de negócio

Faixas de risco usadas pelo servidor: MUITO_BAIXO (<5%) · BAIXO (5–15%) · MODERADO (15–35%) · ALTO (35–60%) · MUITO_ALTO (≥60%).

🌐 Interface Web Chat no Navegador (Streamlit)

O projeto inclui uma interface web conversacional completa construída em Streamlit para demonstrações, testes rápidos e uso operacional por equipes de crédito e underwriting:

make web
# ou: streamlit run app.py

Acesse no seu navegador: http://localhost:8501

✨ Principais Recursos da Interface Web:

• 💬 Chat em Linguagem Natural: Faça perguntas livres sobre clientes, simulações ou carteiras em português.

• ⚡ Ações Rápidas (Todas as 5 Faixas de Risco): Carregue instantaneamente perfis representativos de cada faixa com 1 clique:

  • 🟢 1. Muito Baixo (<5%): Cliente Prime (renda alta, score 910, uso de limite 10%).

  • 🟢 2. Baixo (5–15%): Cliente Saudável (score 810, uso de limite 25%, 0 defaults).

  • 🟡 3. Moderado (15–35%): Cliente Limítrofe (score 580, uso de limite 50%, sem atrasos).

  • 🔴 4. Alto (35–60%): Cliente Alerta (score 580, uso de limite 50%, 1 default recente).

  • ⛔ 5. Muito Alto (≥60%): Cliente Crítico (score 544, uso de limite 73%, 2 inadimplências).

• 🛠️ Grade de Consultas Sugeridas:

  • 📊 Ficha Técnica: Exibe métricas de validação, ROC-AUC, PR-AUC e acurácia.

  • 📁 Carteira CSV: Avalia carteiras inteiras com scoring vetorizado de 11.000 clientes em 0,7s, calculando a Perda Esperada (R$) e exposição total.

  • 📉 Simulação What-If: Simule reduções de limite (30%), quitação de dívidas ou aumento de score (+150 pontos).

  • 🔬 Auditoria SHAP: Ranking e gráficos de barras com os maiores drivers de risco de crédito.

• 💡 Guias Expansíveis para Leigos: Cada resposta contém uma legenda didática explicando o significado dos gráficos SHAP, deltas de probabilidade e provisão de perdas.

🔌 Opção 2: Servidor MCP (Claude Desktop / Claude Code)

# 1. Instalar dependências
pip install -r requirements.txt --break-system-packages   # ou use um venv

# 2. Treinar o modelo (gera models/*.joblib e model_metadata.json)
python -m src.train

# 3. (Opcional) Gerar os gráficos de avaliação em reports/figures/
python -m src.evaluate

# 4. Rodar os testes
pytest -v

# 5. Subir o servidor MCP (stdio)
python -m mcp_server.server

Conectar ao Claude Desktop / Claude Code

Copie mcp_server/claude_desktop_config.example.json para o arquivo de configuração MCP do seu cliente, ajustando os caminhos absolutos:

{
  "mcpServers": {
    "agent-risk-ai": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/caminho/absoluto/para/agent-risk-ai",
      "env": { "PYTHONPATH": "/caminho/absoluto/para/agent-risk-ai" }
    }
  }
}

Reinicie o cliente e pergunte, por exemplo: "Usando o servidor agent-risk-ai, qual o risco deste cliente: ..."

📁 Estrutura do projeto

agent-risk-ai/
├── app.py                       # Interface Web Chat conversacional no navegador (Streamlit)
├── data/raw/                    # train.csv, test.csv, sample_submission.csv
├── src/
│   ├── config.py                 # caminhos, sementes, regras de negócio centralizadas
│   ├── data_processing.py        # limpeza (sentinelas, winsorização, PII)
│   ├── feature_engineering.py    # features de domínio (DTI, utilização, tenure...)
│   ├── pipeline.py                # ColumnTransformer sklearn (sem vazamento)
│   ├── train.py                   # baselines + Optuna + XGBoost + SHAP + persistência
│   ├── evaluate.py                # gera gráficos (ROC, PR, confusão, SHAP)
│   └── inference.py                # camada de predição reutilizada pelo MCP e Web Chat
├── mcp_server/
│   ├── server.py                   # servidor MCP com as 6 ferramentas
│   └── claude_desktop_config.example.json
├── models/                         # modelo treinado + metadados (gerado por train.py)
├── reports/figures/                 # gráficos de avaliação (gerado por evaluate.py)
├── tests/test_pipeline.py            # 7 testes unitários (pytest)
├── requirements.txt
├── Makefile
└── README.md

⚠️ Limitações conhecidas e próximos passos

Transparência sobre limitações é parte de fazer ciência de dados séria:

• LGD assumida em 100% no cálculo de perda esperada (portfolio_risk_summary) por simplicidade — em produção, isso viria de dados históricos de recuperação.

• Sem monitoramento de drift — próximo passo natural seria instrumentar predict_default com logging de distribuição de features ao longo do tempo.

• Calibração de probabilidade não foi validada com CalibratedClassifierCV — as probabilidades são discriminativas (boas para ranquear risco), mas podem não ser perfeitamente calibradas em escala absoluta.

• occupation_type = "Unknown" é a categoria mais frequente (~31% da base) e coincide com o flag de aposentados/não empregados — um refinamento futuro seria desmembrar essa categoria.

🧠 Stack técnica

Python 3.12 · pandas · scikit-learn · XGBoost · Optuna (tuning bayesiano via TPE) · SHAP (explicabilidade) · matplotlib · pytest · MCP Python SDK