# PaPP v2 — Fase 3: classificatore extra-rendimento (architettura)

Architettura del modello che prova a prevedere, al momento di un incrocio, se
l'**extra-rendimento a 10 giorni** (rispetto alla baseline dello stesso regime)
sarà **positivo o no**. È lo scheletro modulare della Fase 3, già pronto per
l'export ONNX della Fase 4.

> Stato: **scaffolding funzionante end-to-end**. Il modello di riferimento è un
> baseline volutamente semplice; i risultati attuali confermano che l'edge è
> debole (vedi sotto) e indicano dove migliorare. L'obiettivo di questa cartella
> è la **struttura**, non ancora un modello ottimizzato.

---

## 1. Idea e target

- **Target** (binario): `1` se `extra-rendimento a 10g > 0`, altrimenti `0`, dove
  `extra = cret_10(incrocio) − media cret_10 della baseline nello stesso regime`.
- **Regime** = `trend (sopra/sotto MA365) × tercile(cluster) × tercile(velocità)`.
- **Feature** (solo informazioni note all'incrocio, nessun esito futuro):
  `dist_med_pct, cluster_pct, cluster_exp, slope_a, slope_b, vel_med, acc_med,
  vol_med` (numeriche) + `pair, dir, trend, dow, month` (categoriche).

### Niente leakage (punto chiave)
Terzili del regime e medie di baseline sono stimati **solo sul training**
(`labeling.RegimeBaseline.fit`) e applicati a validazione/OOS. Così la label di
test non usa mai informazione futura.

---

## 2. Validazione

- **Walk-forward espansivo**: train = tutti gli anni fino a T, test = anno T+1,
  scorrendo T (configurabile `min_train_years`, `step_years`).
- **Hold-out OOS**: tutti gli anni `>= oos_start_year` (default **2020**) sono
  tenuti fuori dal training e usati solo alla fine.

Metriche (`evaluate.py`): AUC, accuracy, Brier, e **precisione/lift sul decile a
probabilità più alta** (uso pratico: si opera solo sui segnali più forti).

---

## 3. Struttura

```
Modello/
├── config.yaml            tutti i parametri (target, regime, feature, split, modello)
├── requirements.txt
├── src/
│   ├── data.py            caricamento CSV + etichetta di regime
│   ├── labeling.py        RegimeBaseline: baseline per regime e target (fit su train)
│   ├── features.py        ColumnTransformer (one-hot + impute), selezione X
│   ├── splits.py          split OOS + walk-forward espansivo
│   ├── model.py           factory modello (hist_gbdt | logistic)
│   ├── evaluate.py        metriche
│   └── train.py           pipeline end-to-end
├── results/               metriche walk-forward + OOS (modello .joblib non versionato)
└── data/                  i 2 CSV di input (non versionati)
```

## 4. Come eseguire

```bash
pip install -r requirements.txt
# copia i 2 CSV in ./data (vedi data/README.md), poi:
cd src
python train.py            # usa ../config.yaml
```

## 5. Risultati attuali (EURUSD, hold-out 2020+)

Con il baseline `hist_gbdt` e tutte le coppie:
- walk-forward medio **AUC ≈ 0.51**, OOS 2020+ **AUC ≈ 0.52**, lift sul decile ≈ 1.0×.

Lettura onesta: **vicino al caso**. È coerente con la Fase 2 (edge direzionali
piccoli) e ci dà un riferimento pulito e senza leakage da cui partire.

## 6. Prossimi miglioramenti previsti

- **Restringere ai pattern robusti** (q<0.10): in `config.yaml` valorizzare
  `restrict_pairs` con gli incroci MA121/MA182/MA365 emersi in Fase 2.
- **Target alternativi**: classificare solo le code (es. extra nel top/bottom 30%)
  invece del semplice segno; oppure regressione sull'extra-rendimento.
- **Feature aggiuntive**: percentile storico delle metriche (come nel pannello),
  interazioni coppia×regime, stato di mean-reversion in corso.
- **Calibrazione** delle probabilità e scelta soglia per massimizzare la
  precisione sui segnali operativi.
- **Fase 4**: export del `Pipeline` in **ONNX** (skl2onnx) e inferenza in MT5.