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)
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

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:

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.