docs: README.md e CLAUDE.md con documentazione progetto completa

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-27 08:04:21 +02:00
parent c44f008e4d
commit 1617330d10
2 changed files with 194 additions and 0 deletions
@@ -0,0 +1,120 @@
+# PythagorasGoal
+
+Sistema di riconoscimento pattern frattali e predizione per il trading di criptovalute (BTC, ETH), ispirato al framework teorico di Serleto & Malanga (*Pythagoras Trading Prediction*).
+
+## Obiettivo
+
+Partendo da un capitale iniziale di €1.000, raggiungere un profitto medio di €50 al giorno entro 6–8 mesi, tramite strategie algoritmiche che combinano analisi frattale, squeeze di volatilità e machine learning.
+
+## Risultati
+
+Tredici strategie testate su dati storici 2018–2026 (BTC e ETH, timeframe 5m / 15m / 1h). Le migliori cinque:
+
+| # | Strategia | Accuracy | ROI annuo | Max DD | €/giorno |
+|---|-----------|----------|-----------|--------|----------|
+| 1 | ETH 15m Squeeze + ML ibrida | 76.9% | 118% | 4.2% | €13.78 |
+| 2 | ETH 1h Squeeze + Vol | 83.9% | 22% | 2.0% | €0.71 |
+| 3 | BTC 15m Squeeze + ML ibrida | 78.8% | 69% | 7.0% | €5.51 |
+| 4 | ETH 1h Squeeze (BBw=30) | 82.8% | 47% | 3.2% | €1.77 |
+| 5 | ETH Walk-Forward ML | 57.7% | 38% | 47% | €3.12 |
+
+La strategia vincente (#1) opera su ETH a 15 minuti con ~1 trade al giorno, leva 3x e drawdown contenuto al 4.2%.
+
+## Come funziona
+
+### Volatility Squeeze Breakout
+
+Il meccanismo centrale sfrutta i cicli naturali di compressione ed espansione della volatilità:
+
+1. **Compressione** — le Bollinger Bands entrano dentro i Keltner Channel (il prezzo si muove sempre meno, accumulando "energia").
+2. **Breakout** — le bande escono dal canale. Un impulso direzionale parte.
+3. **Conferma ML** — un modello GradientBoosting, addestrato su feature strutturali e frattali della finestra precedente, conferma la direzione e filtra i segnali deboli.
+
+### Feature frattali
+
+- Rapporti body/shadow normalizzati su finestre multiple (12, 24, 48 candele)
+- Momentum, volatilità, skewness, kurtosis dei rendimenti logaritmici
+- Autocorrelazione lag-1
+- Profilo volumetrico e spike detection
+- Durata della fase di squeeze e rapporto di espansione Keltner
+- Posizione del prezzo rispetto al range recente e ATR normalizzato
+
+## Struttura progetto
+
+```
+PythagorasGoal/
+├── src/
+│   ├── data/          # Download e gestione dati storici (Cerbero MCP + Binance)
+│   ├── fractal/       # Indicatori frattali: Hurst, Higuchi FD, self-similarity
+│   ├── backtest/      # Motore di backtesting con fee e metriche
+│   ├── strategies/    # (predisposto per strategie modulari)
+│   ├── nn/            # (predisposto per reti neurali)
+│   └── utils/
+├── scripts/           # Script di analisi e test (01–13)
+├── data/
+│   ├── raw/           # Parquet OHLCV (non committati, ~70 MB)
+│   └── processed/     # Modelli salvati
+├── docs/
+│   └── diary/         # Diario di ricerca giornaliero
+├── tests/
+├── pyproject.toml
+└── README.md
+```
+
+## Setup
+
+```bash
+# Clona il repository
+git clone <repo-url> && cd PythagorasGoal
+
+# Installa dipendenze (richiede uv)
+uv sync
+
+# Scarica dati storici (~70 MB, richiede connessione)
+uv run python -m src.data.downloader
+
+# Esegui la strategia ibrida vincente
+uv run python scripts/13_squeeze_ml_hybrid.py
+```
+
+### Requisiti
+
+- Python ≥ 3.11
+- [uv](https://docs.astral.sh/uv/) come package manager
+- Accesso a Cerbero MCP (`cerbero-mcp.tielogic.xyz`) per i dati Deribit, oppure Binance via ccxt come fallback
+
+## Dati
+
+| Asset | Timeframe | Candele | Copertura |
+|-------|-----------|---------|-----------|
+| BTC | 5m / 15m / 1h | 883K / 294K / 74K | 2018-01 → oggi |
+| ETH | 5m / 15m / 1h | 882K / 294K / 74K | 2018-01 → oggi |
+
+Fonte primaria: Deribit perpetual via Cerbero MCP. Fallback per il periodo antecedente: Binance spot via ccxt. Formato: Apache Parquet.
+
+## Strategie testate
+
+| Script | Approccio | Esito |
+|--------|-----------|-------|
+| 01 | Pattern candlestick discreti (U/D/0) | Nessun edge |
+| 02 | DTW pattern matching | Troppo lento, edge minimo |
+| 03 | Proiezione FFT (ispirata al paper) | Random (49.8%) |
+| 04 | GBM su feature frattali (Hurst, FD) | 63.6% a soglia 0.65 |
+| 05 | GBM multi-window (corretto data leakage) | 58.9% |
+| 06 | GBM su feature strutturali normalizzate | 58.6%, +57.5% return |
+| 07 | LSTM su sequenze candele | 58.4%, comparabile a GBM |
+| 08 | Ensemble multi-timeframe (1h + 15m) | 59.2% (consensus 2/3) |
+| 09 | Walk-forward ML | 57.7%, Sharpe 7.4, €3.12/day |
+| 10 | Ensemble 5 modelli alta precisione | In corso |
+| 11 | **Volatility Squeeze Breakout** | **83.9%**, approccio strutturale |
+| 12 | Report finale e simulazione crescita | — |
+| 13 | **Squeeze + ML ibrida** | **76.9%**, 118% ann, €13.78/day |
+
+## Riferimenti
+
+- Serleto, L. & Malanga, C. — *Pythagoras Trading Prediction* (2024)
+- Serleto, L. & Malanga, C. — *Libro dei Frattali* (2024)
+
+## Licenza
+
+Uso privato. Non destinato alla distribuzione.