PaPP v2: Fase 3 - architettura classificatore extra-rendimento (walk-forward + OOS)

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

PaPP v2/Modello/README.md

@@ -0,0 +1,88 @@
+# 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.