💳 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.

---

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.

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)

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

# 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 — MSc Marketing Management, Bocconi. Costruito come pezzo di portfolio per una transizione verso ruoli di Data Science / Corporate Finance.