docs: README.md e CLAUDE.md con documentazione progetto completa
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,74 @@
|
||||
# PythagorasGoal — Istruzioni per agenti
|
||||
|
||||
## Panoramica
|
||||
|
||||
Progetto di ricerca: riconoscimento pattern frattali per trading algoritmico su criptovalute (BTC, ETH). L'obiettivo è arrivare a €50/giorno di profitto partendo da €1.000, entro 6–8 mesi.
|
||||
|
||||
## Stack
|
||||
|
||||
- **Linguaggio:** Python 3.11+
|
||||
- **Package manager:** uv (dipendenze in `pyproject.toml`, lock in `uv.lock`)
|
||||
- **Dati:** Parquet in `data/raw/` (non committati, ~70 MB)
|
||||
- **ML:** scikit-learn (GradientBoosting), PyTorch (LSTM)
|
||||
- **Analisi:** numpy, pandas, scipy
|
||||
- **API dati:** Cerbero MCP su `cerbero-mcp.tielogic.xyz` (Deribit, Bybit, Hyperliquid), ccxt/Binance come fallback
|
||||
|
||||
## Struttura
|
||||
|
||||
```
|
||||
src/data/ → download e caricamento dati (downloader.py)
|
||||
src/fractal/ → indicatori frattali (patterns.py, indicators.py, similarity.py)
|
||||
src/backtest/ → engine di backtesting (engine.py)
|
||||
scripts/ → analisi e strategie numerate 01–13
|
||||
docs/diary/ → diario di ricerca giornaliero
|
||||
data/raw/ → file .parquet OHLCV (gitignored)
|
||||
data/processed/ → modelli salvati (gitignored)
|
||||
```
|
||||
|
||||
## Comandi
|
||||
|
||||
```bash
|
||||
uv sync # installa dipendenze
|
||||
uv run python -m src.data.downloader # scarica dati storici
|
||||
uv run python scripts/13_squeeze_ml_hybrid.py # strategia vincente
|
||||
uv run pytest # test
|
||||
```
|
||||
|
||||
## Dati storici
|
||||
|
||||
Scaricati e salvati localmente in Parquet. Per rigenerarli:
|
||||
|
||||
```python
|
||||
from src.data.downloader import download_all, load_data
|
||||
download_all() # scarica BTC + ETH su 5m/15m/1h dal 2018
|
||||
df = load_data("ETH", "15m") # carica un asset/timeframe
|
||||
```
|
||||
|
||||
Fonte primaria: Cerbero MCP (endpoint `/mcp-deribit/tools/get_historical`).
|
||||
Token observer: nel file `secrets/observer.token` del progetto CerberoSuite.
|
||||
|
||||
## Strategia vincente
|
||||
|
||||
**Squeeze + ML ibrida** (script 13):
|
||||
|
||||
1. Rileva squeeze di volatilità (Bollinger dentro Keltner)
|
||||
2. Al rilascio dello squeeze, estrai feature strutturali dalla finestra
|
||||
3. GradientBoosting predice direzione con walk-forward training
|
||||
4. Trade solo se modello ha confidenza ≥ 70%
|
||||
|
||||
Configurazione migliore: ETH 15m, BBw=14, squeeze threshold=0.8, breakout=3 barre, leva 3x, position 15%.
|
||||
|
||||
Risultato backtestato: 76.9% accuracy, 118% annuo, 4.2% drawdown, €13.78/giorno da €1.000.
|
||||
|
||||
## Convenzioni
|
||||
|
||||
- Script numerati progressivamente (`01_`, `02_`, …). Ogni script è autocontenuto.
|
||||
- Diario in `docs/diary/YYYY-MM-DD.md`. Aggiornare dopo ogni esperimento significativo.
|
||||
- Nessun dato sensibile nei commit (token, chiavi API). Usare `.gitignore`.
|
||||
- Verificare sempre assenza di data leakage prima di fidarsi dei risultati. In particolare: `returns[i-w : i]` include `close[i]` che è un candle nel futuro — usare `returns[i-w : i-1]`.
|
||||
|
||||
## Attenzione
|
||||
|
||||
- **Data leakage:** è stata trovata e corretta nello script 05. Ogni volta che si usano rendimenti logaritmici (`np.diff(np.log(close))`), ricordare che `returns[k]` usa `close[k+1]`. I feature devono fermarsi a `returns[i-2]` se il prezzo corrente è `close[i-1]`.
|
||||
- **Fee:** sempre 0.1% per lato (0.2% round-trip). Includere nel backtest.
|
||||
- **Leva:** testato con 3x. Aumentare a 5x migliora i rendimenti ma raddoppia il drawdown.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user