🏦 Агент кредитного риска ИИ (Agent Risk AI) — ML + MCP Server

Агент кредитного риска ИИ: Ваш автономный аналитик кредитного интеллекта и риска через MCP. Модель прогнозирования дефолта по кредитной карте, обученная с методологической строгостью (стратифицированная кросс-валидация, байесовская настройка с Optuna, оптимизированный порог, объяснимость через SHAP) и представленная как MCP-сервер — доступная напрямую через Claude Desktop/Code и ИИ-агентов на естественном языке.

📌 Почему этот проект отличается от «просто обучить модель»

Большинство портфельных проектов останавливаются на обучении модели и показе .ipynb с метриками. Этот идёт дальше: модель инкапсулирована в MCP-сервер (Model Context Protocol) с 6 бизнес-инструментами, что означает, что любой совместимый LLM-хост (Claude Desktop, Claude Code) может обращаться к модели на естественном языке, без написания кода:

🗣️ «Каков риск дефолта этого клиента: возраст 46, доход 107 934 R$, кредитный скоринг 544, 2 предыдущих просрочки?» 🤖 → вызывает predict_default → отвечает с вероятностью, классом и SHAP-объяснением.

Это именно тот паттерн, который сейчас появляется в командах по рискам/данным, желающих включить продакшн-модели «в разговор», а не за статичным дашбордом.

Related MCP server: CreddyMCP

🗂️ Бизнес-задача

Датасет из 45 528 клиентов кредитных карт с демографическими переменными, доходом и кредитным поведением. Целевая переменная: credit_card_default (бинарная), с реальным дисбалансом 8,1% дефолтов — типичный сценарий кредитного риска, где наивная точность — вводящая в заблуждение метрика.

🏗️ Как работает система (простая архитектура)

Проект превращает сырые кредитные данные в действенные и проверяемые решения, потребляемые ИИ-агентами через 4 интегрированных этапа:

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>"]

Поток из 4 шагов:

1. 📁 1. Обработка и финансовая аналитика (data_processing.py / feature_engineering.py)

   • Удаляет чувствительные данные (PII) и обрабатывает аномалии датасета (например, сентинел для пенсионеров).

   • Создаёт реальные финансовые показатели: Debt-to-Income (DTI), использование лимита и доход на душу населения.

2. 🤖 2. Конвейер машинного обучения (pipeline.py / train.py)

   • Выполняет преобразования (импутация, one-hot кодирование и масштабирование) изолированно (без утечки данных).

   • Обучает и настраивает XGBoost через Optuna (25 испытаний) на 5-фолдовой кросс-валидации, калибруя оптимальный порог решения ($F_1 = 0,875$).

3. 🧠 3. Объяснимость и аудит (inference.py / evaluate.py)

   • Сохраняет лучшую модель и SHAP TreeExplainer для разложения того, какие именно переменные повышают или снижают риск каждого клиента в реальном времени.

4. 🔌 4. Агентный слой MCP (mcp_server/server.py)

   • Предоставляет 6 готовых инструментов, чтобы любой ассистент или ИИ-агент (Claude Desktop, Claude Code и т.д.) мог обращаться к модели, моделировать сценарии и оценивать целые портфели на естественном языке.

🔬 Инженерия признаков, ориентированная на предметную область

Вместо того чтобы «свалить всё в XGBoost», каждый производный признак имеет явное обоснование кредитного риска:

🧪 Методология и статистическая строгость

• Винзоризация, обученная только на тренировочных данных (процентиль 99,5%) и повторно применённая на тесте/холдауте — без утечки данных.

• Единый sklearn-конвейер (ColumnTransformer + модель) — импутация и кодирование пересчитываются на каждом фолде кросс-валидации, а не один раз на всём датасете (распространённая ошибка, искусственно завышающая метрики).

• Метрика выбора: PR-AUC (Average Precision), а не ROC-AUC и не точность — правильный выбор при 8% распространённости положительного класса.

• Холдаут 15%, никогда не виденный во время настройки Optuna — финальные метрики ниже отражают реальное обобщение, а не переобучение на процесс поиска.

• Порог решения перекалиброван для максимизации F1 на кривой precision-recall холдаута (0,875), вместо слепого использования 0,5 — это важно, когда положительный класс редок.

• Объяснимость через SHAP TreeExplainer — каждое предсказание MCP-сервера может быть проверено пофакторно (актуально для регуляторного соответствия в кредитовании).

📊 Результаты и метрики производительности

Все метрики ниже рассчитаны на холдаут-наборе (6 830 клиентов), полностью изолированном во время поиска гиперпараметров Optuna:

1. Сравнение моделей (стратифицированная 5-фолдовая кросс-валидация)

2. Метрики производительности на холдауте (модель-победитель)

3. Детальная матрица ошибок на холдауте

4. Победившие гиперпараметры (Optuna — 25 испытаний)

{
  "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. Топ-10 проверяемых факторов риска (средняя важность $|\text{SHAP}|$)

📈 Визуальные артефакты в reports/figures/:

• roc_curve.png — ROC-кривая со случайным базовым уровнем.

• precision_recall_curve.png — Кривая Precision-Recall в сравнении с базовой распространённостью.

• confusion_matrix.png — Матрица ошибок при оптимальном пороге.

• shap_summary.png — Beeswarm summary plot глобальной объяснимости.

🔒 Все указанные выше метрики воспроизводимы и сохраняются в метаданных аудита в models/model_metadata.json.

💡 Руководство по интерпретации результатов (для неспециалистов и бизнеса)

Для облегчения коммуникации между специалистами по данным, кредитными аналитиками и нетехническими директорами, каждый выход системы имеет прямое бизнес-значение:

1. 📈 Вероятность дефолта (PD) и диапазоны действий

• Что это: Оценённая вероятность (от 0% до 100%) того, что клиент просрочит оплату счёта более чем на 90 дней в последующие месяцы.

• Как действовать в зависимости от диапазона:

  • 🟢 MUITO_BAIXO (< 5%) и BAIXO (5%–15%): Выдача кредита и увеличение лимита рекомендуются автоматически с конкурентными ставками.

  • 🟡 MODERADO (15%–35%): Пограничный клиент. Рекомендуется консервативный начальный лимит или запрос подтверждения дохода.

  • 🔴 ALTO (35%–60%) и MUITO_ALTO (≥ 60%): Высокий риск просрочки. Рекомендуется отказ от предложения или требование поручителей/реального обеспечения.

2. 📊 Как читать график объяснимости SHAP

• 🔴 Полосы вправо (положительный вклад): Кадастровые или поведенческие факторы, которые повышают риск (например, низкий балл, чрезмерное использование револьверного лимита, предыдущая просрочка).

• 🟢 Полосы влево (отрицательный вклад): Здоровые факторы, которые защищают клиента и снижают риск (например, многолетняя стабильность на работе, высокий доход, высокий балл).

• 📏 Длина полосы: Чем длиннее полоса, тем более решающей была эта переменная для окончательного вердикта ИИ.

3. 📉 Что такое симуляция What-If?

• Позволяет моделировать влияние изменений в правилах или давать рекомендации отклонённым клиентам. Например: «Если вы снизите использование вашего лимита с 73% до 30%, ваш риск упадёт с 68% до 22%, что позволит одобрить вашу карту».

4. 💰 Общая экспозиция и ожидаемые потери портфеля

• Общая экспозиция: Общий финансовый объём, который учреждение поставило на кон (сумма предоставленных кредитных лимитов).

• Ожидаемые потери ($PD \times \text{Экспозиция}$): Сумма в реалах, которую учреждение статистически прогнозирует потерять из-за просрочек, если не будут приняты никакие меры.

• Ставка потерь (%): Прямая основа для резерва на возможные потери по ссудам (PDD / IFRS 9).

🔌 MCP-сервер — 6 бизнес-инструментов

Диапазоны риска, используемые сервером: MUITO_BAIXO (<5%) · BAIXO (5–15%) · MODERADO (15–35%) · ALTO (35–60%) · MUITO_ALTO (≥60%).

🌐 Веб-интерфейс чата в браузере (Streamlit)

Проект включает полноценный веб-интерфейс с разговорным чатом, построенный на Streamlit, для демонстраций, быстрых тестов и оперативного использования командами кредитования и андеррайтинга:

make web
# ou: streamlit run app.py

Откройте в браузере: http://localhost:8501

✨ Основные возможности веб-интерфейса:

• 💬 Чат на естественном языке: Задавайте свободные вопросы о клиентах, симуляциях или портфелях на португальском.

• ⚡ Быстрые действия (все 5 диапазонов риска): Загружайте репрезентативные профили для каждого диапазона в один клик:

  • 🟢 1. Очень низкий (<5%): Prime-клиент (высокий доход, балл 910, использование лимита 10%).

  • 🟢 2. Низкий (5–15%): Здоровый клиент (балл 810, использование лимита 25%, 0 просрочек).

  • 🟡 3. Умеренный (15–35%): Пограничный клиент (балл 580, использование лимита 50%, без задержек).

  • 🔴 4. Высокий (35–60%): Клиент-сигнал тревоги (балл 580, использование лимита 50%, 1 недавняя просрочка).

  • ⛔ 5. Очень высокий (≥60%): Критический клиент (балл 544, использование лимита 73%, 2 просрочки).

• 🛠️ Сетка предлагаемых запросов:

  • 📊 Технический паспорт: Отображает метрики валидации, ROC-AUC, PR-AUC и точность.

  • 📁 Портфель CSV: Оценивает целые портфели с векторизованным скорингом 11 000 клиентов за 0,7 с, рассчитывая ожидаемые потери (R$) и общую экспозицию.

  • 📉 Симуляция What-If: Моделируйте снижение лимита (30%), погашение долгов или повышение балла (+150 пунктов).

  • 🔬 Аудит SHAP: Ранжирование и столбчатые диаграммы с основными драйверами кредитного риска.

• 💡 Раскрывающиеся руководства для неспециалистов: Каждый ответ содержит пояснительную подпись, объясняющую значение графиков SHAP, дельт вероятности и резерва на потери.

🔌 Вариант 2: 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

Подключение к Claude Desktop / Claude Code

Скопируйте mcp_server/claude_desktop_config.example.json в файл конфигурации MCP вашего клиента, отрегулировав абсолютные пути:

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

Перезапустите клиент и спросите, например: «Используя сервер agent-risk-ai, каков риск этого клиента: ...»

📁 Структура проекта

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

⚠️ Известные ограничения и следующие шаги

Прозрачность в отношении ограничений — часть серьёзной науки о данных:

• LGD принята за 100% при расчёте ожидаемых потерь (portfolio_risk_summary) для простоты — в производстве это должно поступать из исторических данных о взыскании.

• Нет мониторинга дрейфа — следующим естественным шагом было бы инструментирование predict_default журналированием распределения признаков с течением времени.

• Калибровка вероятности не была проверена с помощью CalibratedClassifierCV — вероятности являются дискриминативными (хороши для ранжирования риска), но могут не быть идеально откалиброваны в абсолютной шкале.

• occupation_type = "Unknown" — самая частая категория (~31% базы) и совпадает с флагом пенсионеров/безработных — будущим уточнением было бы разделение этой категории.

🧠 Технический стек

Python 3.12 · pandas · scikit-learn · XGBoost · Optuna (байесовская настройка через TPE) · SHAP (объяснимость) · matplotlib · pytest · MCP Python SDK