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

Agente de Riesgo IA: Su analista autónomo de inteligencia y riesgo de crédito vía MCP. Un modelo de predicción de impago de tarjeta de crédito, entrenado con rigor metodológico (CV estratificada, tuning bayesiano con Optuna, umbral optimizado, explicabilidad vía SHAP) y expuesto como servidor MCP — consultable directamente por Claude Desktop/Code y agentes de IA en lenguaje natural.

📌 Por qué este proyecto es diferente de "solo entrenar un modelo"

La mayoría de los proyectos de portafolio se quedan en entrenar el modelo y mostrar un .ipynb con métricas. Este va un paso más allá: el modelo está encapsulado en un servidor MCP (Model Context Protocol) con 6 herramientas de negocio, lo que significa que cualquier host LLM compatible (Claude Desktop, Claude Code) puede consultar el modelo en lenguaje natural, sin escribir código:

🗣️ "¿Cuál es el riesgo de impago de este cliente: edad 46, ingresos R$107.934, score de crédito 544, 2 impagos anteriores?" 🤖 → llama a predict_default → responde con probabilidad, clase y explicación SHAP.

Esto es exactamente el patrón que está emergiendo en equipos de riesgo/datos que quieren poner modelos de producción "en la conversación", no detrás de un dashboard estático.

Related MCP server: CreddyMCP

🗂️ El problema de negocio

Dataset de 45.528 clientes de tarjeta de crédito con variables demográficas, de ingresos y de comportamiento crediticio. Objetivo: credit_card_default (binario), con desequilibrio real de 8,1% de impagos — escenario típico de riesgo de crédito, donde la precisión ingenua es una métrica engañosa.

🏗️ Cómo Funciona el Sistema (Arquitectura Simple)

El proyecto transforma datos brutos de crédito en decisiones accionables y auditables consumidas por agentes de IA a travé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>"]

El Flujo en 4 Pasos:

1. 📁 1. Tratamiento e Inteligencia Financiera (data_processing.py / feature_engineering.py)

   • Elimina datos sensibles (PII) y trata anomalías del dataset (como el centinela de jubilados).

   • Crea indicadores financieros reales: Debt-to-Income (DTI), utilización de límite e ingresos per cápita.

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

   • Ejecuta transformaciones (imputación, one-hot encoding y escala) de forma estanca (sin fuga de datos).

   • Entrena y ajusta el XGBoost vía Optuna (25 trials) en validación cruzada 5-fold, calibrando el umbral de decisión óptimo ($F_1 = 0,875$).

3. 🧠 3. Explicabilidad y Auditoría (inference.py / evaluate.py)

   • Persiste el modelo ganador y el SHAP TreeExplainer para descomponer exactamente qué variables aumentan o reducen el riesgo de cada cliente en tiempo real.

4. 🔌 4. Capa Agéntica MCP (mcp_server/server.py)

   • Expone 6 herramientas listas para que cualquier asistente o agente de IA (Claude Desktop, Claude Code, etc.) pueda consultar el modelo, simular escenarios y evaluar carteras enteras en lenguaje natural.

🔬 Ingeniería de features orientada a dominio

En lugar de "echarlo todo al XGBoost", cada feature derivada tiene una justificación de riesgo de crédito explícita:

🧪 Metodología y rigor estadístico

• Winsorización aprendida solo en el entrenamiento (percentil 99,5%) y reaplicada en el test/holdout — sin fuga de datos.

• Pipeline sklearn único (ColumnTransformer + modelo) — imputación y encoding se recalculan en cada fold de la validación cruzada, no una sola vez en el dataset completo (error común que infla métricas artificialmente).

• Métrica de selección: PR-AUC (Average Precision), no ROC-AUC ni exactitud — la elección correcta para 8% de prevalencia de la clase positiva.

• Holdout de 15% nunca visto durante el tuning del Optuna — las métricas finales siguientes son de generalización real, no de overfitting al proceso de búsqueda.

• Umbral de decisión recalibrado maximizando F1 en la curva precisión-recall del holdout (0,875), en lugar de usar 0,5 a ciegas — esencial cuando la clase positiva es rara.

• Explicabilidad vía SHAP TreeExplainer — cada predicción del servidor MCP puede auditarse factor a factor (relevante para el cumplimiento normativo de crédito).

📊 Resultados y Métricas de Rendimiento

Todas las métricas siguientes se calcularon en el conjunto de holdout (6.830 clientes), completamente aislado durante la búsqueda de hiperparámetros con Optuna:

1. Comparativa de Modelos (Validación Cruzada Estratificada 5-Fold)

2. Métricas de Rendimiento en el Holdout (Modelo Campeón)

3. Matriz de Confusión Detallada en el Holdout

4. Hiperparámetros Ganadores (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 Factores de Riesgo Auditables (Importancia Media $|\text{SHAP}|$)

📈 Artefactos Visuales en reports/figures/:

• roc_curve.png — Curva ROC con línea base aleatoria.

• precision_recall_curve.png — Curva Precisión-Recall comparada con la prevalencia base.

• confusion_matrix.png — Matriz de confusión en el umbral óptimo.

• shap_summary.png — Gráfico de resumen beeswarm de explicabilidad global.

🔒 Todas las métricas anteriores son reproducibles y se guardan en el metadato de auditoría en models/model_metadata.json.

💡 Guía de Interpretación de los Resultados (Para Legos y Negocios)

Para facilitar la comunicación entre científicos de datos, analistas de crédito y directores no técnicos, cada salida del sistema tiene un significado de negocio directo:

1. 📈 Probabilidad de Default (PD) y Rangos de Acción

• ¿Qué es? La probabilidad estimada (de 0% a 100%) de que el cliente retrase el pago de la factura más de 90 días en los meses siguientes.

• ¿Cómo actuar según el rango?

  • 🟢 MUY_BAJO (< 5%) y BAJO (5% a 15%): Concesión de crédito y aumento de límite recomendados de forma automática con tasas competitivas.

  • 🟡 MODERADO (15% a 35%): Cliente límite. Se recomienda un límite inicial conservador o solicitar comprobación de ingresos.

  • 🔴 ALTO (35% a 60%) y MUY_ALTO (≥ 60%): Riesgo elevado de impago. Se recomienda rechazo de la propuesta o exigencia de avalistas/garantías reales.

2. 📊 Cómo Leer el Gráfico de Explicabilidad SHAP

• 🔴 Barras hacia la DERECHA (Contribución Positiva): Factores registrales o de comportamiento que empujan el riesgo hacia ARRIBA (ej: puntuación baja, uso excesivo del límite rotativo, impago previo).

• 🟢 Barras hacia la IZQUIERDA (Contribución Negativa): Factores saludables que protegen al cliente y empujan el riesgo hacia ABAJO (ej: estabilidad de años en el empleo, ingresos altos, puntuación alta).

• 📏 Longitud de la Barra: Cuanto más larga sea la barra, más decisiva fue esa variable para el veredicto final de la IA.

3. 📉 ¿Qué es la Simulación What-If?

• Permite simular el impacto de cambios en reglas o guiar a clientes rechazados. Por ejemplo: "Si reduces la utilización de tu límite del 73% al 30%, tu riesgo bajará del 68% al 22%, permitiendo la aprobación de tu tarjeta."

4. 💰 Exposición Total y Pérdida Esperada de la Cartera

• Exposición Total: El volumen financiero total que la institución puso en juego (suma de los límites de crédito concedidos).

• Pérdida Esperada ($PD \times \text{Exposición}$): El valor en Reales que la institución proyecta perder estadísticamente por impago si no se toma ninguna acción.

• Tasa de Pérdida (%): Base directa para la Provisión para Deudores Dudosos (PDD / IFRS 9).

🔌 El servidor MCP — 6 herramientas de negocio

Rangos de riesgo usados por el servidor: MUY_BAJO (<5%) · BAJO (5–15%) · MODERADO (15–35%) · ALTO (35–60%) · MUY_ALTO (≥60%).

🌐 Interfaz Web Chat en el Navegador (Streamlit)

El proyecto incluye una interfaz web conversacional completa construida en Streamlit para demostraciones, pruebas rápidas y uso operativo por equipos de crédito y suscripción:

make web
# ou: streamlit run app.py

Accede en tu navegador: http://localhost:8501

✨ Principales Características de la Interfaz Web:

• 💬 Chat en Lenguaje Natural: Haz preguntas libres sobre clientes, simulaciones o carteras en español.

• ⚡ Acciones Rápidas (Todos los 5 Rangos de Riesgo): Carga instantáneamente perfiles representativos de cada rango con 1 clic:

  • 🟢 1. Muy Bajo (<5%): Cliente Prime (ingresos altos, puntuación 910, uso de límite 10%).

  • 🟢 2. Bajo (5–15%): Cliente Saludable (puntuación 810, uso de límite 25%, 0 impagos).

  • 🟡 3. Moderado (15–35%): Cliente Límite (puntuación 580, uso de límite 50%, sin retrasos).

  • 🔴 4. Alto (35–60%): Cliente Alerta (puntuación 580, uso de límite 50%, 1 impago reciente).

  • ⛔ 5. Muy Alto (≥60%): Cliente Crítico (puntuación 544, uso de límite 73%, 2 impagos).

• 🛠️ Cuadrícula de Consultas Sugeridas:

  • 📊 Ficha Técnica: Muestra métricas de validación, ROC-AUC, PR-AUC y precisión.

  • 📁 Cartera CSV: Evalúa carteras completas con puntuación vectorizada de 11.000 clientes en 0,7s, calculando la Pérdida Esperada (R$) y la exposición total.

  • 📉 Simulación What-If: Simula reducciones de límite (30%), liquidación de deudas o aumento de puntuación (+150 puntos).

  • 🔬 Auditoría SHAP: Ranking y gráficos de barras con los mayores impulsores de riesgo de crédito.

• 💡 Guías Expandibles para Legos: Cada respuesta contiene una leyenda didáctica que explica el significado de los gráficos SHAP, deltas de probabilidad y provisión de pérdidas.

🔌 Opción 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 a Claude Desktop / Claude Code

Copia mcp_server/claude_desktop_config.example.json al archivo de configuración MCP de tu cliente, ajustando las rutas absolutas:

{
  "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" }
    }
  }
}

Reinicia el cliente y pregunta, por ejemplo: "Usando el servidor agent-risk-ai, ¿cuál es el riesgo de este cliente: ..."

📁 Estructura del proyecto

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

⚠️ Limitaciones conocidas y próximos pasos

La transparencia sobre las limitaciones es parte de hacer ciencia de datos seria:

• LGD asumida al 100% en el cálculo de pérdida esperada (portfolio_risk_summary) por simplicidad — en producción, esto vendría de datos históricos de recuperación.

• Sin monitoreo de deriva — el siguiente paso natural sería instrumentar predict_default con registro de distribución de características a lo largo del tiempo.

• Calibración de probabilidad no fue validada con CalibratedClassifierCV — las probabilidades son discriminativas (buenas para clasificar riesgo), pero pueden no estar perfectamente calibradas en escala absoluta.

• occupation_type = "Unknown" es la categoría más frecuente (~31% de la base) y coincide con el indicador de jubilados/no empleados — un refinamiento futuro sería desglosar esa categoría.

🧠 Stack técnica

Python 3.12 · pandas · scikit-learn · XGBoost · Optuna (ajuste bayesiano vía TPE) · SHAP (explicabilidad) · matplotlib · pytest · MCP Python SDK