🏦 신용위험 AI 에이전트 (Agent Risk AI) — ML + MCP 서버

신용위험 AI 에이전트: MCP를 통한 자율 신용 인텔리전스 및 위험 분석가. 엄격한 방법론(층화 교차검증, Optuna 베이지안 튜닝, 최적화된 임계값, SHAP 설명 가능성)으로 훈련된 신용카드 채무불이행 예측 모델을 MCP 서버로 제공 — Claude Desktop/Code 및 AI 에이전트가 자연어로 직접 조회할 수 있습니다.

📌 이 프로젝트가 "모델 훈련만 하는 것"과 다른 이유

대부분의 포트폴리오 프로젝트는 모델을 훈련하고 .ipynb로 지표를 보여주는 데서 그칩니다. 이 프로젝트는 한 단계 더 나아갑니다: 모델이 6개의 비즈니스 도구를 갖춘 MCP 서버(Model Context Protocol)에 캡슐화되어 있어, 호환되는 모든 LLM 호스트 (Claude Desktop, Claude Code)가 코드 작성 없이 자연어로 모델을 조회할 수 있습니다:

🗣️ "이 고객의 채무불이행 위험은 얼마인가요: 나이 46세, 소득 R$107,934, 신용 점수 544, 이전 채무불이행 2건?" 🤖 → predict_default 호출 → 확률, 클래스, SHAP 설명으로 응답.

이것은 정적 대시보드 뒤가 아니라 "대화 속에" 프로덕션 모델을 배치하려는 위험/데이터 팀에서 떠오르고 있는 바로 그 패턴입니다.

Related MCP server: CreddyMCP

🗂️ 비즈니스 문제

45,528명의 신용카드 고객 데이터셋으로 인구통계, 소득, 신용 행동 변수를 포함합니다. 목표 변수: credit_card_default(이진), **실제 불균형 8.1%**의 채무불이행률 — 신용위험의 전형적인 시나리오로, 단순 정확도는 오해를 불러일으키는 지표입니다.

🏗️ 시스템 작동 방식 (간단한 아키텍처)

이 프로젝트는 원시 신용 데이터를 4단계 통합 프로세스를 통해 AI 에이전트가 소비하는 실행 가능하고 감사 가능한 의사결정으로 변환합니다:

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)를 제거하고 데이터셋의 이상값(은퇴자 센티널 등)을 처리합니다.

   • 실제 금융 지표 생성: 부채-소득 비율(DTI), 한도 사용률, 1인당 소득.

2. 🤖 2. 머신러닝 파이프라인 (pipeline.py / train.py)

   • 변환(결측값 대체, 원-핫 인코딩, 스케일링)을 격리된 상태로 실행(데이터 누수 없음).

   • Optuna(25 trials)로 XGBoost를 5-fold 교차검증에서 훈련 및 튜닝하고, 최적 결정 임계값을 보정($F_1 = 0.875$).

3. 🧠 3. 설명 가능성 및 감사 (inference.py / evaluate.py)

   • 최적 모델과 SHAP TreeExplainer를 저장하여 각 고객의 위험을 높이거나 낮추는 정확한 변수를 실시간으로 분해합니다.

4. 🔌 4. MCP 에이전트 계층 (mcp_server/server.py)

   • 모든 AI 어시스턴트 또는 에이전트(Claude Desktop, Claude Code 등)가 자연어로 모델을 조회하고, 시나리오를 시뮬레이션하며, 전체 포트폴리오를 평가할 수 있는 6개의 도구를 제공합니다.

🔬 도메인 중심 피처 엔지니어링

"모든 것을 XGBoost에 넣기" 대신, 각 파생 피처에는 명시적인 신용위험 근거가 있습니다:

🧪 방법론 및 통계적 엄격성

• 훈련 데이터에서만 학습된 Winsorization(99.5 백분위수)을 테스트/홀드아웃에 재적용 — 데이터 누수 없음.

• 단일 sklearn 파이프라인(ColumnTransformer + 모델) — 결측값 대체와 인코딩이 전체 데이터셋에 한 번만 적용되는 것이 아니라 교차검증의 각 폴드마다 재계산됩니다 (지표를 인위적으로 부풀리는 흔한 오류).

• 선택 지표: PR-AUC (Average Precision) — ROC-AUC나 정확도가 아닌, 양성 클래스 비율 8%에 대한 올바른 선택.

• Optuna 튜닝 중 전혀 보지 못한 15% 홀드아웃 — 아래 최종 지표는 검색 과정에 대한 과적합이 아닌 실제 일반화 성능입니다.

• 결정 임계값 재보정 — 양성 클래스가 희소할 때 필수적인, 홀드아웃의 정밀도-재현율 곡선에서 F1을 최대화(0.875)하는 임계값을 맹목적인 0.5 대신 사용.

• SHAP TreeExplainer를 통한 설명 가능성 — MCP 서버의 각 예측은 요인별로 감사 가능(신용 규제 준수에 중요).

📊 결과 및 성능 지표

아래 모든 지표는 Optuna의 하이퍼파라미터 탐색 중 완전히 격리된 홀드아웃 세트(6,830명 고객) 에서 계산되었습니다:

1. 모델 비교 (층화 5-Fold 교차검증)

2. 홀드아웃 성능 지표 (최적 모델)

3. 홀드아웃 상세 혼동 행렬

4. 최적 하이퍼파라미터 (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. 감사 가능한 상위 10대 위험 요인 (평균 $|\text{SHAP}|$ 중요도)

📈 시각적 산출물은 reports/figures/에 있습니다:

• roc_curve.png — 무작위 기준선이 포함된 ROC 곡선.

• precision_recall_curve.png — 기본 유병률과 비교한 정밀도-재현율 곡선.

• confusion_matrix.png — 최적 임계값에서의 혼동 행렬.

• shap_summary.png — 전역 설명 가능성의 Beeswarm 요약 플롯.

🔒 위의 모든 지표는 재현 가능하며 models/model_metadata.json의 감사 메타데이터에 저장됩니다.

💡 결과 해석 가이드 (비전문가 및 비즈니스 담당자용)

데이터 과학자, 신용 분석가, 비기술 임원 간의 커뮤니케이션을 원활하게 하기 위해, 시스템의 각 출력은 직접적인 비즈니스 의미를 갖습니다:

1. 📈 채무불이행 확률(PD) 및 조치 구간

• 정의: 고객이 향후 수개월 내에 청구서 결제를 90일 이상 지연할 추정 확률(0%~100%).

• 구간별 조치 방법:

  • 🟢 매우 낮음 (< 5%) 및 낮음 (5%~15%): 경쟁력 있는 금리로 신용 부여 및 한도 증액을 자동으로 권장.

  • 🟡 중간 (15%~35%): 경계선 고객. 보수적인 초기 한도 또는 소득 증빙 요청 권장.

  • 🔴 높음 (35%~60%) 및 매우 높음 (≥ 60%): 채무불이행 위험이 높음. 제안 거절 또는 연대보증인/실물 담보 요구 권장.

2. 📊 SHAP 설명 가능성 그래프 읽는 방법

• 🔴 오른쪽 막대(긍정 기여): 위험을 높이는 등록 또는 행동 요인 (예: 낮은 점수, 회전 한도 과다 사용, 과거 채무불이행).

• 🟢 왼쪽 막대(부정 기여): 고객을 보호하고 위험을 낮추는 건전한 요인 (예: 수년간의 고용 안정성, 높은 소득, 높은 점수).

• 📏 막대 길이: 막대가 길수록 해당 변수가 AI의 최종 판정에 더 결정적이었음을 의미합니다.

3. 📉 What-If 시뮬레이션이란?

• 규칙 변경의 영향을 시뮬레이션하거나 거절된 고객을 안내하는 데 사용됩니다. 예: "신용 한도 사용률을 73%에서 30%로 낮추면 위험이 68%에서 22%로 낮아져 카드 승인이 가능해집니다."

4. 💰 총 노출 및 포트폴리오 기대 손실

• 총 노출: 기관이 노출시킨 총 금융 규모(부여된 신용 한도의 합계).

• 기대 손실 ($PD \times \text{노출}$): 아무 조치도 취하지 않을 경우 기관이 채무불이행으로 인해 통계적으로 손실할 것으로 예상되는 금액(헤알).

• 손실률(%): 대손충당금(PDD / IFRS 9)의 직접적인 근거.

🔌 MCP 서버 — 비즈니스 도구 6종

서버에서 사용하는 위험 구간: 매우 낮음 (<5%) · 낮음 (5–15%) · 중간 (15–35%) · 높음 (35–60%) · 매우 높음 (≥60%).

🌐 브라우저 웹 채팅 인터페이스 (Streamlit)

이 프로젝트에는 Streamlit으로 구축된 완전한 대화형 웹 인터페이스가 포함되어 있어, 신용 및 언더라이팅 팀의 데모, 빠른 테스트, 운영 사용에 적합합니다:

make web
# ou: streamlit run app.py

브라우저에서 접속하세요: http://localhost:8501

✨ 웹 인터페이스 주요 기능:

• 💬 자연어 채팅: 포르투갈어로 고객, 시뮬레이션 또는 포트폴리오에 대해 자유롭게 질문하세요.

• ⚡ 빠른 실행(전체 5개 위험 구간): 클릭 한 번으로 각 구간의 대표 프로필을 즉시 불러옵니다:

  • 🟢 1. 매우 낮음 (<5%): 프라임 고객(고소득, 점수 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