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/SQ02_squeeze_antifake_vol.py  # miglior strategia robusta
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().

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	Filtered	Regole	79.2%	Filtri selezionabili (9 preset)
SQ04	Ultimate	Regole	81.6%	Max accuracy ma concentrato 2018
ML01	Squeeze+GBM	ML	78.8%	Walk-forward, €8-12/day, DD basso

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

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.