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 (GradientBoostingClassifier)
• Analisi: numpy, pandas, scipy
• API dati: Cerbero MCP su cerbero-mcp.tielogic.xyz (Deribit, Bybit, Hyperliquid), ccxt/Binance come fallback
• Config: pyyaml per strategies.yml

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
src/live/              → paper trading live multi-strategia
  multi_runner.py      → orchestratore: carica YAML, fetch candele, tick worker
  strategy_worker.py   → worker indipendente: capital, trade log, stato persistente
  strategy_loader.py   → import dinamico classi Strategy da scripts/strategies/
  cerbero_client.py    → client HTTP per Cerbero MCP (Deribit testnet)
  signal_engine.py     → squeeze + ML real-time (per ML01)
  telegram_notifier.py → notifiche Telegram per trade
scripts/strategies/    → strategie attive (SQ01-SQ04, ML01)
scripts/waste/         → strategie scartate (W01-W22 + REF originali)
scripts/analysis/      → script di confronto e report
strategies.yml         → config multi-strategy paper trader
docs/diary/            → diario di ricerca giornaliero
docs/specs/            → specifiche di design
data/raw/              → file .parquet OHLCV (gitignored)

Comandi

uv sync                                              # installa dipendenze
uv run python -m src.data.downloader                  # scarica dati storici
uv run python scripts/strategies/MT01_squeeze_mtf_momentum.py  # miglior strategia (82.7% acc)
uv run python scripts/analysis/yearly_market_report.py         # confronto per anno×mercato
uv run python scripts/strategies/ML01_squeeze_gbm.py  # squeeze + ML (GBM)
uv run python -m src.live.multi_runner                # paper trading live multi-strategia
docker compose up -d                                  # deploy Docker
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.

Strategie attive

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

Accuracy/DD su BTC 15m (9 anni 2018-2026, fee 0.2% RT, leva 3x, pos 15%):

Codice	Nome	Tipo	Acc	DD	Trades	Note
SQ01	Squeeze Base	Regole	76.7%	6.7%	4062	Squeeze breakout puro, baseline
SQ02	Antifake+Vol	Regole	79.7%	6.5%	1250	Squeeze + antifake + volume
SQ03	Filtered	Regole	79.2%	—	—	Filtri selezionabili (9 preset)
SQ04	Ultimate	Regole	81.6%	4.3%	376	Concentrato 2018, poco robusto
ML01	Squeeze+GBM	ML	78.8%	7.0%	1964	Walk-forward, €8-12/day
MT01	Squeeze+MTF	Regole	82.7%	5.9%	503	Max accuracy — squeeze 15m + EMA trend 1h
PD01	Price-Vol Divergence	Regole	80.6%	2.7%	578	Volume TREND al breakout, DD bassissimo
CM01	Cross-Market Momentum	Regole	79.5%	2.2%*	611	Squeeze + momentum cross BTC↔ETH (*DD su ETH)
AD01	Adaptive Squeeze	Regole	79.9%	9.9%	1364	Soglia squeeze adattiva per regime vol, max PnL

Le strategie MT01/PD01/CM01/AD01 (branch strategy4) battono SQ02 e hanno DD inferiore (eccetto AD01 su BTC). PD01 ed CM01 su ETH raggiungono DD 2.2-2.3%. Report dettagliato per anno×mercato: scripts/analysis/yearly_market_report.py.

Per aggiungere una strategia:

1. Crea script in scripts/strategies/ che estende Strategy
2. Aggiungi mapping in src/live/strategy_loader.py → MODULE_MAP
3. Aggiungi entry in strategies.yml per paper trading

Strategie scartate in scripts/waste/ (W23-W28): inside bar, donchian, retest, mean reversion RSI, volume spike, squeeze+MR — tutte sotto 65% acc o DD >14%.

Multi-Strategy Paper Trader

Orchestratore che esegue N strategie in parallelo su dati live Cerbero, ognuna con €1000 USDC virtuali indipendenti.

Config: strategies.yml — lista strategie con asset, tf, sizing, parametri. Persistenza: data/paper_trades/{strategy}___{asset}__{tf}/ con trades.jsonl (append-only) + status.json (resume al restart). Hot-add: aggiungi riga YAML → docker compose restart → storico intatto. Notifiche: Telegram per ogni trade (richiede .env con TELEGRAM_BOT_TOKEN e TELEGRAM_CHAT_ID).

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.
• GBM: GradientBoostingClassifier di scikit-learn. Ensemble di alberi decisionali sequenziali. Walk-forward per evitare leakage temporale.