🏦 AIリスクエージェント（Agent Risk AI）— ML + MCPサーバー

AIリスクエージェント: MCP経由で利用できる、あなたの自律型クレジット知能・リスクアナリスト。 厳格な方法論（層化交差検証、Optunaによるベイズチューニング、最適化された閾値、SHAPによる 説明可能性）で訓練されたクレジットカード債務不履行予測モデルをMCPサーバーとして公開 — Claude Desktop/CodeやAIエージェントから自然言語で直接照会できます。

📌 このプロジェクトが「モデルを訓練するだけ」と違う理由

ほとんどのポートフォリオプロジェクトは、モデルを訓練してメトリクス付きの.ipynbを 示すだけで終わります。これはさらに一歩進んでいます。モデルはMCPサーバー （Model Context Protocol）にカプセル化され、6つのビジネスツールを備えているため、 互換性のある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%**の 債務不履行率 — クレジットリスクの典型的なシナリオであり、単純な正解率は誤解を招く メトリクスです。

🏗️ システムの仕組み（シンプルなアーキテクチャ）

このプロジェクトは、生のクレジットデータを、AIエージェントが消費できる実践的かつ監査可能な意思決定へと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）

   • 変換（欠損値補完、ワンホットエンコーディング、スケーリング）を漏れなく（データ漏洩なしで）実行します。

   • XGBoostをOptuna（25トライアル）で5分割交差検証により訓練・調整し、最適な決定閾値を較正します（$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に放り込む」のではなく、各派生特徴量には明示的なクレジットリスクの 根拠があります：

🧪 方法論と統計的厳密性

• 訓練データのみで学習したウィンソライズ（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分割交差検証）

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 — ベース有病率と比較した適合率-再現率曲線。

• confusion_matrix.png — 最適閾値における混同行列。

• shap_summary.png — グローバルな説明可能性のBeeswarmサマリープロット。

🔒 上記のすべての指標は再現可能であり、models/model_metadata.json の監査メタデータに保存されます。

💡 結果の解釈ガイド（非技術者・ビジネス向け）

データサイエンティスト、信用アナリスト、非技術系の役員間のコミュニケーションを円滑にするため、システムの各出力には直接的なビジネス上の意味があります：

1. 📈 デフォルト確率（PD）とアクション区分

• 概要： 顧客が今後数ヶ月以内に請求書の支払いを90日以上遅延する推定確率（0%〜100%）。

• 区分に基づく対応方法：

  • 🟢 MUITO_BAIXO（5%未満）および BAIXO（5%〜15%）： 競争力のある金利での自動的な与信付与と限度額引き上げを推奨。

  • 🟡 MODERADO（15%〜35%）： 境界線上の顧客。保守的な初期限度額または収入証明の要求を推奨。

  • 🔴 ALTO（35%〜60%）および MUITO_ALTO（60%以上）： 債務不履行リスクが高い。申し込みの拒否、または保証人・物的担保の要求を推奨。

2. 📊 SHAP説明可能性グラフの読み方

• 🔴 右向きのバー（正の寄与）： リスクを上昇させる登録情報・行動要因（例：低スコア、リボルビング枠の過剰使用、過去の債務不履行）。

• 🟢 左向きのバー（負の寄与）： 顧客を保護しリスクを低下させる健全な要因（例：長年の雇用安定性、高収入、高スコア）。

• 📏 バーの長さ： バーが長いほど、その変数がAIの最終判定においてより決定的であったことを示します。

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%以上）。

🌐 ブラウザ上のWebチャットインターフェース（Streamlit）

このプロジェクトには、Streamlit で構築された完全な対話型Webインターフェースが含まれており、デモ、クイックテスト、信用・引受チームによる運用利用を目的としています：

make web
# ou: streamlit run app.py

ブラウザでアクセス：http://localhost:8501

✨ Webインターフェースの主な機能：

• 💬 自然言語チャット： 顧客、シミュレーション、ポートフォリオについてポルトガル語で自由に質問できます。

• ⚡ クイックアクション（全5リスク区分）： 1クリックで各区分の代表的なプロフィールを即座に読み込みます：

  • 🟢 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