# 💳 Credit Risk Intelligence System

**Un sistema di credit scoring che valuta il rischio di un cliente e spiega la sua decisione in linguaggio naturale — un modello statistico interpretabile e verificato fa i calcoli, 4 agenti AI (Claude) li orchestrano e li raccontano.**

[![Repository](https://img.shields.io/badge/GitHub-repository-blue)](https://github.com/Alessandro-Donnini/credit-risk-intelligence-system)

---

## In azione

Un utente compila i dati di un cliente in un form web (nessun terminale richiesto), e il sistema restituisce in pochi secondi: probabilità di default, spiegazione dei fattori che l'hanno determinata, verifica di quanto ci si può fidare della previsione, e rapporti finanziari — il tutto scritto come un vero credit memo.

```powershell
streamlit run src/agents/app.py
```

> **Esempio di output** (cliente con storico di pagamento regolare ma limite di credito e rimborsi contenuti):
> **PD: 44.72%** — rischio medio-alto · **Affidabilità: alta** (cliente tipico, 99.91° percentile) · **Fattore protettivo principale:** pagamento puntuale (PAY_0) · **Fattore di rischio principale:** rimborsi storicamente bassi rispetto al limite concesso

## Come funziona, in breve

```
                         ┌─────────────────────┐
                         │   SUPERVISOR AGENT   │
                         │  (sintetizza tutto)  │
                         └──────────┬───────────┘
                                    │
        ┌───────────────┬──────────┼──────────┬───────────────┐
        │                │                     │                │
        ▼                ▼                     ▼                ▼
┌───────────────┐ ┌──────────────┐  ┌──────────────────┐ ┌──────────────┐
│  Risk Modeling │ │Explainability│  │      Critic       │ │  Rapporti    │
│     Agent      │ │    Agent     │  │      Agent        │ │  finanziari  │
│                │ │              │  │                    │ │              │
│ "Quanto rischia│ │  "Perché?"   │  │"Posso fidarmi di   │ │"Come si      │
│  questo        │ │  (SHAP)      │  │ questa previsione?"│ │ comporta il  │
│  cliente?"     │ │              │  │ (Mahalanobis)      │ │ cliente?"    │
└───────┬────────┘ └──────┬───────┘  └─────────┬──────────┘ └──────┬───────┘
        │                 │                     │                   │
        └─────────────────┴──────────┬──────────┴───────────────────┘
                                      ▼
                    ┌──────────────────────────────────┐
                    │   MODELLO STATISTICO (Logistic     │
                    │   Regression, AUC-ROC 0.7629)      │
                    │   L'UNICA fonte di ogni numero.    │
                    │   Nessun agente inventa mai una    │
                    │   probabilità o un contributo.     │
                    └──────────────────────────────────┘
```

Ogni agente chiama uno strumento Python deterministico (mai una stima "a mente" della LLM) e traduce il risultato in linguaggio naturale. Lo stesso modello è raggiungibile anche via **server MCP** standard, verificato con l'MCP Inspector ufficiale.

## Risultati

| Metrica | Valore |
|---|---|
| AUC-ROC (test set / 5-fold CV) | 0.7629 / 0.7717 ± 0.0087 |
| Recall @ soglia ottimizzata | 0.8117 |
| Variabile più predittiva | `PAY_0` (storico pagamento recente), IV = 0.898 |
| Test automatici | 21, tutti superati |
| Costo medio per credit memo | ≈ $0.03 (misurato) |

![Curva ROC](models/roc_curve.png)

## Perché è più di un modello

Molti progetti di data science si fermano al modello. Questo va oltre, con scelte metodologiche esplicite e verificate:

- **Nessun data leakage**: ogni calcolo statistico (WOE, binning, PSI) usa solo il train set, mai il test.
- **Due modelli confrontati onestamente**: Logistic Regression scelta sopra Gradient Boosting nonostante quest'ultimo ottenga metriche leggermente superiori — il guadagno non giustificava la perdita di interpretabilità in un contesto normato come il credito.
- **Explainability verificata matematicamente**: i contributi SHAP di ogni cliente ricostruiscono esattamente, cifra per cifra, la probabilità del modello.
- **Robustezza**: limite di iterazioni sugli agenti, gestione degli errori di rete e di input malformato, validazione dei dati in ingresso, guardrail espliciti sullo scopo — non solo "il caso felice".
- **Limiti dichiarati, non nascosti**: l'Expected Loss usa stime di settore per LGD/EAD (non presenti nel dataset), documentato esplicitamente nel codice.

## Come lanciare il progetto

```powershell
# Ambiente
python -m venv venv && .\venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

# Pipeline dati -> modello (necessaria prima di usare gli agenti)
python src\data\run_pipeline.py

# Interfaccia web
streamlit run src\agents\app.py

# Oppure un singolo agente da terminale
python src\agents\supervisor_agent.py

# Test automatici
python -m pytest tests\ -v

# Server MCP (richiede Node.js per l'Inspector)
npx @modelcontextprotocol/inspector python src\agents\mcp_server.py
```

Richiede una `ANTHROPIC_API_KEY` in un file `.env` nella root del progetto.

## Il dataset

**"Default of Credit Card Clients"**, UCI Machine Learning Repository (Yeh & Lien, 2009). 30.000 clienti reali di carte di credito a Taiwan, 23 variabili esplicative, licenza CC BY 4.0.

## Approfondimenti tecnici

<details>
<summary><strong>Sistema multi-agente, in dettaglio</strong></summary>

- **Risk Modeling Agent** — chiama `score_new_client`, mai genera il numero da solo.
- **Explainability Agent** — chiama `explain_client_shap` (SHAP con `LinearExplainer`, esatto per modelli lineari).
- **Critic Agent** — chiama `check_client_typicality` (distanza di Mahalanobis), usa Claude Haiku per contenere i costi su un compito semplice.
- **Supervisor Agent** — orchestra tutti gli strumenti sopra più `calculate_financial_ratios`, dà priorità esplicita agli avvisi di atipicità o dati implausibili nella sintesi finale.

Verificato concretamente: lo stesso cliente valutato tramite script diretto, tre agenti diversi, e il server MCP produce sempre lo stesso identico risultato (0.4472).

</details>

<details>
<summary><strong>Metodologia del modello, in dettaglio</strong></summary>

- **Data Quality Assessment**: 345 anomalie corrette in `EDUCATION`, 54 in `MARRIAGE`; un caso analogo in `PAY_0...PAY_6` (valori `-2`/`0` non documentati ma strutturali) identificato e volutamente non "corretto", perché parte reale del dataset.
- **Selezione delle feature** su Information Value e matrice di correlazione: escluse `MARRIAGE` (IV troppo basso) e le 6 `BILL_AMT` (IV bassissimo e correlate tra loro).
- **Soglia di decisione** ottimizzata su un criterio di business esplicito (Recall ≥ 0.80), con il trade-off in Precision quantificato, non ignorato.

</details>

<details>
<summary><strong>Struttura del progetto</strong></summary>

```
├── data/raw/                # dataset grezzo
├── models/                  # modello, trasformazioni, grafici
├── src/
│   ├── data/                # pipeline: caricamento, pulizia, feature engineering, training
│   └── agents/               # 4 agenti Claude, server MCP, interfaccia Streamlit
└── tests/                   # 21 test automatici
```

</details>

---

*Progetto di [Alessandro Donnini](https://github.com/Alessandro-Donnini) — MSc Marketing Management, Bocconi. Costruito come pezzo di portfolio per una transizione verso ruoli di Data Science / Corporate Finance.*