🏦 KI-Risikoagent (Agent Risk AI) — ML + MCP-Server

KI-Risikoagent: Ihr autonomer Analyst für Kreditintelligenz und -risiko über MCP. Ein Modell zur Vorhersage von Kreditkartenzahlungsausfällen, trainiert mit methodischer Strenge (stratifizierte Kreuzvalidierung, Bayes'sches Tuning mit Optuna, optimierter Schwellenwert, Erklärbarkeit über SHAP) und als MCP-Server bereitgestellt — direkt abfragbar über Claude Desktop/Code und KI-Agenten in natürlicher Sprache.

📌 Warum sich dieses Projekt von „nur ein Modell trainieren" unterscheidet

Die meisten Portfolio-Projekte hören beim Trainieren des Modells und dem Zeigen eines .ipynb mit Metriken auf. Dieses geht einen Schritt weiter: Das Modell ist in einen MCP-Server (Model Context Protocol) mit 6 Geschäftswerkzeugen gekapselt, was bedeutet, dass jeder kompatible LLM-Host (Claude Desktop, Claude Code) das Modell in natürlicher Sprache abfragen kann, ohne Code zu schreiben:

🗣️ „Wie hoch ist das Ausfallrisiko dieses Kunden: Alter 46, Einkommen 107.934 R$, Kredit-Score 544, 2 frühere Zahlungsverzüge?" 🤖 → ruft predict_default auf → antwortet mit Wahrscheinlichkeit, Klasse und SHAP-Erklärung.

Genau das ist das Muster, das sich in Risiko-/Datenteams herausbildet, die Produktionsmodelle „ins Gespräch" bringen wollen, nicht hinter ein statisches Dashboard.

Related MCP server: CreddyMCP

🗂️ Das Geschäftsproblem

Datensatz von 45.528 Kreditkartenkunden mit demografischen Variablen, Einkommens- und Kreditverhaltensvariablen. Zielvariable: credit_card_default (binär), mit realem Ungleichgewicht von 8,1 % Zahlungsausfällen — ein typisches Szenario im Kreditrisiko, bei dem naive Genauigkeit eine irreführende Metrik ist.

🏗️ Wie das System funktioniert (Einfache Architektur)

Das Projekt wandelt rohe Kreditdaten in umsetzbare und prüfbare Entscheidungen um, die von KI-Agenten über 4 integrierte Schritte konsumiert werden:

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

Der Ablauf in 4 Schritten:

1. 📁 1. Aufbereitung & Finanzintelligenz (data_processing.py / feature_engineering.py)

   • Entfernt sensible Daten (PII) und behandelt Anomalien im Datensatz (wie den Sentinel-Wert für Rentner).

   • Erstellt echte Finanzkennzahlen: Debt-to-Income (DTI), Kreditlinienauslastung und Pro-Kopf-Einkommen.

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

   • Führt Transformationen (Imputation, One-Hot-Encoding und Skalierung) dicht aus (ohne Datenleck).

   • Trainiert und optimiert den XGBoost über Optuna (25 Trials) in 5-facher Kreuzvalidierung und kalibriert den optimalen Entscheidungsschwellenwert ($F_1 = 0,875$).

3. 🧠 3. Erklärbarkeit & Auditierung (inference.py / evaluate.py)

   • Persistiert das Siegermodell und den SHAP TreeExplainer, um in Echtzeit genau zu zerlegen, welche Variablen das Risiko jedes Kunden erhöhen oder senken.

4. 🔌 4. Agentische MCP-Schicht (mcp_server/server.py)

   • Stellt 6 einsatzbereite Werkzeuge bereit, damit jeder Assistent oder KI-Agent (Claude Desktop, Claude Code usw.) das Modell abfragen, Szenarien simulieren und ganze Portfolios in natürlicher Sprache bewerten kann.

🔬 Domänenorientiertes Feature-Engineering

Statt „alles in XGBoost zu werfen", hat jedes abgeleitete Feature eine explizite Begründung im Kreditrisiko:

🧪 Methodik und statistische Strenge

• Winsorisierung nur auf dem Training gelernt (99,5. Perzentil) und auf dem Test-/Holdout-Set erneut angewendet — ohne Datenleck.

• Einheitliche sklearn-Pipeline (ColumnTransformer + Modell) — Imputation und Encoding werden bei jedem Fold der Kreuzvalidierung neu berechnet, nicht nur einmal auf dem gesamten Datensatz (ein häufiger Fehler, der Metriken künstlich aufbläht).

• Auswahlmetrik: PR-AUC (Average Precision), nicht ROC-AUC oder Genauigkeit — die richtige Wahl bei 8 % Prävalenz der positiven Klasse.

• Holdout von 15 %, das während des Optuna-Tunings nie gesehen wurde — die endgültigen Metriken unten sind echte Generalisierung, kein Overfitting an den Suchprozess.

• Neu kalibrierter Entscheidungsschwellenwert, der F1 auf der Precision-Recall-Kurve des Holdouts maximiert (0,875), statt blind 0,5 zu verwenden — entscheidend, wenn die positive Klasse selten ist.

• Erklärbarkeit über SHAP TreeExplainer — jede Vorhersage des MCP-Servers kann Faktor für Faktor geprüft werden (relevant für die regulatorische Compliance im Kreditwesen).

📊 Ergebnisse und Leistungsmetriken

Alle untenstehenden Metriken wurden auf dem Holdout-Set (6.830 Kunden) berechnet, das während der Hyperparametersuche durch Optuna vollständig isoliert war:

1. Modellvergleich (Stratifizierte 5-Fold-Kreuzvalidierung)

2. Leistungsmetriken auf dem Holdout (Siegermodell)

3. Detaillierte Konfusionsmatrix auf dem Holdout

4. Sieger-Hyperparameter (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 prüfbare Risikofaktoren (Durchschnittliche Bedeutung $|\text{SHAP}|$)

📈 Visuelle Artefakte in reports/figures/:

• roc_curve.png — ROC-Kurve mit zufälliger Basislinie.

• precision_recall_curve.png — Präzisions-Recall-Kurve im Vergleich zur Basisprävalenz.

• confusion_matrix.png — Konfusionsmatrix beim optimalen Schwellenwert.

• shap_summary.png — Beeswarm-Zusammenfassungsdiagramm der globalen Erklärbarkeit.

🔒 Alle oben genannten Metriken sind reproduzierbar und werden in den Audit-Metadaten unter models/model_metadata.json gespeichert.

💡 Leitfaden zur Interpretation der Ergebnisse (Für Laien und Geschäftsanwender)

Um die Kommunikation zwischen Data Scientists, Kreditanalysten und nicht-technischen Führungskräften zu erleichtern, hat jede Systemausgabe eine direkte geschäftliche Bedeutung:

1. 📈 Ausfallwahrscheinlichkeit (PD) & Handlungsbereiche

• Was ist das: Die geschätzte Wahrscheinlichkeit (0% bis 100%), dass der Kunde die Rechnungszahlung in den folgenden Monaten um mehr als 90 Tage verzögert.

• Wie Sie basierend auf der Stufe handeln:

  • 🟢 MUITO_BAIXO (< 5%) e BAIXO (5% a 15%): Kreditvergabe und Limit-Erhöhung automatisch mit wettbewerbsfähigen Konditionen empfohlen.

  • 🟡 MODERADO (15% a 35%): Grenzfall-Kunde. Konservatives Anfanglimit oder Einkommensnachweis empfohlen.

  • 🔴 ALTO (35% a 60%) e MUITO_ALTO (≥ 60%): Hohes Ausfallrisiko. Ablehnung des Antrags oder Forderung von Bürgen/Sachgarantien empfohlen.

2. 📊 So lesen Sie das SHAP-Erklärbarkeitsdiagramm

• 🔴 Balken nach RECHTS (positiver Beitrag): Registrierungs- oder Verhaltensfaktoren, die das Risiko nach OBEN ziehen (z. B. niedriger Score, übermäßige Nutzung des revolvierenden Limits, frühere Zahlungsausfälle).

• 🟢 Balken nach LINKS (negativer Beitrag): Gesunde Faktoren, die den Kunden schützen und das Risiko nach UNTEN ziehen (z. B. jahrelange Beschäftigungsstabilität, hohes Einkommen, hoher Score).

• 📏 Balkenlänge: Je länger der Balken, desto entscheidender war diese Variable für das endgültige KI-Urteil.

3. 📉 Was ist die What-If-Simulation?

Ermöglicht die Simulation der Auswirkungen von Regeländerungen oder die Beratung abgelehnter Kunden. Zum Beispiel: „Wenn Sie Ihre Limit-Auslastung von 73% auf 30% reduzieren, sinkt Ihr Risiko von 68% auf 22%, sodass Ihre Karte genehmigt werden kann."

4. 💰 Gesamtengagement und erwarteter Verlust des Portfolios

• Gesamtengagement: Das gesamte finanzielle Volumen, das das Institut aufs Spiel gesetzt hat (Summe der gewährten Kreditlimits).

• Erwarteter Verlust ($PD \times \text{Exposição}$): Der Betrag in Reais, den das Institut statistisch durch Zahlungsausfälle verlieren würde, wenn keine Maßnahmen ergriffen werden.

• Verlustquote (%): Direkte Grundlage für die Rückstellung für zweifelhafte Forderungen (PDD / IFRS 9).

🔌 Der MCP-Server — 6 Geschäftswerkzeuge

Vom Server verwendete Risikostufen: MUITO_BAIXO (<5%) · BAIXO (5–15%) · MODERADO (15–35%) · ALTO (35–60%) · MUITO_ALTO (≥60%).

🌐 Web-Chat-Oberfläche im Browser (Streamlit)

Das Projekt enthält eine vollständige konversationelle Weboberfläche, die mit Streamlit erstellt wurde, für Demonstrationen, schnelle Tests und den operativen Einsatz durch Kredit- und Underwriting-Teams:

make web
# ou: streamlit run app.py

Zugriff in Ihrem Browser: http://localhost:8501

✨ Hauptfunktionen der Weboberfläche:

• 💬 Chat in natürlicher Sprache: Stellen Sie freie Fragen zu Kunden, Simulationen oder Portfolios auf Portugiesisch.

• ⚡ Schnellaktionen (alle 5 Risikostufen): Laden Sie mit einem Klick sofort repräsentative Profile jeder Stufe:

  • 🟢 1. Sehr niedrig (<5%): Prime-Kunde (hohes Einkommen, Score 910, Limit-Auslastung 10%).

  • 🟢 2. Niedrig (5–15%): Gesunder Kunde (Score 810, Limit-Auslastung 25%, 0 Ausfälle).

  • 🟡 3. Moderat (15–35%): Grenzfall-Kunde (Score 580, Limit-Auslastung 50%, keine Verzögerungen).

  • 🔴 4. Hoch (35–60%): Warn-Kunde (Score 580, Limit-Auslastung 50%, 1 kürzlicher Ausfall).

  • ⛔ 5. Sehr hoch (≥60%): Kritischer Kunde (Score 544, Limit-Auslastung 73%, 2 Zahlungsausfälle).

• 🛠️ Raster vorgeschlagener Abfragen:

  • 📊 Technisches Datenblatt: Zeigt Validierungsmetriken, ROC-AUC, PR-AUC und Genauigkeit.

  • 📁 CSV-Portfolio: Bewertet ganze Portfolios mit vektorisiertem Scoring von 11.000 Kunden in 0,7s und berechnet den erwarteten Verlust (R$) und das Gesamtengagement.

  • 📉 What-If-Simulation: Simulieren Sie Limit-Reduzierungen (30%), Schuldentilgung oder Score-Erhöhung (+150 Punkte).

  • 🔬 SHAP-Audit: Ranking und Balkendiagramme mit den größten Treibern des Kreditrisikos.

• 💡 Erweiterbare Leitfäden für Laien: Jede Antwort enthält eine didaktische Legende, die die Bedeutung der SHAP-Diagramme, Wahrscheinlichkeitsdeltas und Verlustrückstellungen erklärt.

🔌 Option 2: MCP-Server (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

Verbinden mit Claude Desktop / Claude Code

Kopieren Sie mcp_server/claude_desktop_config.example.json in die MCP-Konfigurationsdatei Ihres Clients und passen Sie die absoluten Pfade an:

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

Starten Sie den Client neu und fragen Sie zum Beispiel: „Mit dem Server agent-risk-ai, wie hoch ist das Risiko dieses Kunden: ..."

📁 Projektstruktur

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

⚠️ Bekannte Einschränkungen und nächste Schritte

Transparenz über Einschränkungen ist Teil seriöser Datenwissenschaft:

• LGD mit 100% angenommen bei der Berechnung des erwarteten Verlusts (portfolio_risk_summary) aus Einfachheit — in Produktion würde dies aus historischen Wiederherstellungsdaten stammen.

• Kein Drift-Monitoring — der natürliche nächste Schritt wäre, predict_default mit Protokollierung der Feature-Verteilung im Laufe der Zeit zu instrumentieren.

• Wahrscheinlichkeitskalibrierung wurde nicht mit CalibratedClassifierCV validiert — die Wahrscheinlichkeiten sind diskriminativ (gut zum Risiko-Ranking), aber möglicherweise nicht perfekt auf absoluter Skala kalibriert.

• occupation_type = "Unknown" ist die häufigste Kategorie (~31% der Basis) und fällt mit dem Kennzeichen für Rentner/Nicht-Beschäftigte zusammen — eine zukünftige Verfeinerung wäre, diese Kategorie aufzuteilen.

🧠 Technischer Stack

Python 3.12 · pandas · scikit-learn · XGBoost · Optuna (Bayes'sches Tuning via TPE) · SHAP (Erklärbarkeit) · matplotlib · pytest · MCP Python SDK