PythagorasGoal/CLAUDE.md

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)
src/strategies/        → classe base Strategy ABC + indicatori condivisi
  base.py              → Strategy, Signal, BacktestResult, YearlyStats
  indicators.py        → keltner_ratio, detect_squeezes, ema, atr, rv, correlation
scripts/strategies/    → strategie attive (SQ01-SQ04, ML01)
scripts/waste/         → strategie scartate (W01-W22 + REF originali)
scripts/analysis/      → script di confronto e report
docs/diary/            → diario di ricerca giornaliero
data/raw/              → file .parquet OHLCV (gitignored)
data/processed/        → modelli salvati (gitignored)

Comandi

uv sync                                              # installa dipendenze
uv run python -m src.data.downloader                  # scarica dati storici
uv run python scripts/strategies/SQ02_squeeze_antifake_vol.py  # miglior strategia robusta
uv run python scripts/strategies/ML01_squeeze_gbm.py  # squeeze + ML (GBM)
uv run pytest                                         # test

Dati storici

Scaricati e salvati localmente in Parquet. Per rigenerarli:

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.

Strategie attive

Codice	Nome	Tipo	Accuracy	Note
SQ01	Squeeze Base	Regole	76.7%	Squeeze breakout puro, baseline
SQ02	Antifake+Vol	Regole	79.7%	Miglior robusto — 9 anni, Sharpe 5.01
SQ03	All Filters	Regole	79.2%	Cross-asset + timing + long squeeze
SQ04	Ultimate	Regole	81.6%	Max accuracy ma concentrato 2018
ML01	Squeeze+GBM	ML	78.8%	Walk-forward, €12/day, DD basso

Tutte le strategie estendono src.strategies.base.Strategy con interfaccia comune: generate_signals() → backtest() → report().

Convenzioni

• Strategie in scripts/strategies/ con codice univoco (SQ01, ML01, ...).
• Script scartati in scripts/waste/ con prefisso W01-W22.
• 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.