# 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

> ⚠️ **Revisione 2026-05-28.** La famiglia squeeze-breakout (SQ/MT/ML/AD/CM/PD, con
> accuracy storiche dichiarate 76-82%) è stata **scartata**: quei numeri erano un
> **artefatto di look-ahead**. I backtest decidevano la direzione dalla candela di
> breakout `close[i]` ma entravano a `close[i-1]` — impossibile dal vivo. Sotto
> ingresso onesto (`close[i]`) e fee reali, l'edge sparisce e tutte perdono, anche
> a fee zero. Dettagli e prove: `scripts/analysis/oos_validation.py`.

Dopo una validazione **out-of-sample, fee-aware** di tutte le famiglie, l'unica con
edge netto reale è il **mean-reversion** (i breakout *rientrano*, non continuano):

| Codice | Strategia | Mercato | Edge OOS netto | Max DD | Robustezza |
|--------|-----------|---------|----------------|--------|------------|
| **MR01** | Bollinger Fade (mean-reversion) | BTC 1h | **+196 / +201%** | 15% | ✅ |
| **MR01** | Bollinger Fade (mean-reversion) | ETH 1h | **+251%** | ~25% | ⚠️ DD alto |

Netto dopo **fee realistiche Deribit 0.10% RT** (taker), leva 3x, pos 15%, su finestra
held-out (nov 2023→mag 2026). MR01 è positivo su **tutta** la griglia parametri
(`n∈{14,20,30,50}` × `k∈{2.0,2.5,3.0}`) e per **ogni** livello di fee 0.00-0.20% RT —
margine di sicurezza ampio, niente parametro fortunato. Ri-validato col worker live reale.

## Come funziona

### MR01 — Bollinger Fade (mean-reversion)

La strategia attiva sfrutta il fatto, emerso dai dati, che su BTC/ETH a 1h gli estremi
di prezzo **rientrano verso la media** più di quanto proseguano:

1. **Bollinger Bands** (window `n`, `k` deviazioni standard) sul close.
2. **Entry** — quando il close esce *sotto* la banda inferiore → **long** (o *sopra* la superiore → **short**). Ingresso a `close[i]`, eseguibile dal vivo.
3. **Take-profit** alla media mobile (il rientro atteso).
4. **Stop-loss** a `sl_atr × ATR` oltre l'estremo; **time-limit** a `max_bars`.

Nessun look-ahead: direzione e livelli sono calcolati con dati fino a `close[i]`.

### Perché lo squeeze breakout è stato abbandonato

L'ipotesi originale era opposta — *continuazione* dopo la compressione di volatilità
(Bollinger dentro Keltner → breakout direzionale). Su dati storici sembrava dare
76-82% di accuracy, ma era un **artefatto di look-ahead**: il backtest entrava a
`close[i-1]` con direzione decisa da `close[i]`. Replicando l'esecuzione reale
(ingresso a `close[i]`) l'edge collassa al ~47% (lancio di moneta) e i costi fanno
il resto. Il test sui breakout intra-barra a 5m conferma che il movimento *rientra*
subito (mean-reversion), giustificando MR01. Tutta la famiglia squeeze è in `scripts/waste/`.

### Lezione metodologica

Ogni nuova strategia deve passare: (1) **ingresso eseguibile** senza look-ahead,
(2) backtest **netto** dopo fee realistiche (0.10% RT Deribit), (3) validazione
**out-of-sample** + robustezza su griglia parametri + sweep fee. Strumenti in
`scripts/analysis/` (`strategy_research.py`, `oos_validation.py`, `intrabar_test.py`).

## Struttura progetto

```
PythagorasGoal/
├── src/
│   ├── data/              # Download e gestione dati (Cerbero MCP + Binance)
│   ├── fractal/           # Indicatori frattali: Hurst, Higuchi FD, self-similarity
│   ├── backtest/          # Motore di backtesting con fee e metriche
│   ├── strategies/        # Classe base Strategy ABC + indicatori condivisi
│   │   ├── base.py        # Strategy, Signal, BacktestResult, YearlyStats
│   │   └── indicators.py  # keltner_ratio, detect_squeezes, ema, atr, rv, corr
│   └── live/              # Paper trading live su Deribit testnet
│       ├── multi_runner.py     # Orchestratore multi-strategia
│       ├── strategy_worker.py  # Worker indipendente con stato persistente
│       ├── strategy_loader.py  # Import dinamico classi Strategy
│       ├── cerbero_client.py   # Client HTTP per Cerbero MCP
│       ├── signal_engine.py    # Squeeze + ML real-time (legacy) + validazione OOS
│       └── telegram_notifier.py
├── scripts/
│   ├── strategies/        # Strategie con edge validato OOS (solo MR01_bollinger_fade)
│   ├── waste/             # Strategie scartate (W01-W28 + famiglia squeeze SQ/MT/ML/AD/CM/PD)
│   └── analysis/          # Ricerca/validazione OOS fee-aware (strategy_research, oos_validation, ...)
├── strategies.yml         # Config multi-strategy paper trader
├── data/
│   └── raw/               # Parquet OHLCV (gitignored, ~70 MB)
├── docs/
│   ├── diary/             # Diario di ricerca giornaliero
│   └── specs/             # Specifiche di design
├── Dockerfile
├── docker-compose.yml
└── pyproject.toml
```

## Strategie attive

Tutte le strategie estendono `src.strategies.base.Strategy` (`generate_signals() → backtest()`).

| Codice | Script | Tipo | Descrizione |
|--------|--------|------|-------------|
| **MR01** | `MR01_bollinger_fade.py` | Mean-reversion | Fada la banda di Bollinger, TP alla media, SL ad ATR. Unica con edge netto validato OOS. |

La famiglia squeeze (SQ01-04, ML01, MT01, PD01, CM01, AD01) è in `scripts/waste/`:
edge storico = artefatto di look-ahead (vedi sezione *Come funziona*).

Per eseguire il backtest della strategia:

```bash
uv run python scripts/strategies/MR01_bollinger_fade.py
```

Per la ricerca/validazione fee-aware out-of-sample:

```bash
uv run python scripts/analysis/strategy_research.py     # screening famiglie + deep-dive MR01
uv run python scripts/analysis/oos_validation.py        # perche' la famiglia squeeze e' scartata
uv run python scripts/analysis/validate_worker_mr01.py  # replay del worker live su MR01
```

## Paper Trading Live

Il multi-strategy runner esegue N strategie in parallelo su dati live da Cerbero MCP, ognuna con €1000 USDC virtuali indipendenti. Se un `Signal` porta `tp`/`sl`/`max_bars` in `metadata` (come MR01), il worker chiude su take-profit alla media / stop-loss ad ATR / time-limit; altrimenti usa il fallback `hold_bars`/stop -2%.

### Avvio

```bash
# Locale
uv run python -m src.live.multi_runner

# Docker
docker compose up -d
```

### Configurazione

Le strategie attive sono definite in `strategies.yml`:

```yaml
defaults:
  capital: 1000
  position_size: 0.15
  leverage: 3

strategies:
  - name: MR01_bollinger_fade
    asset: BTC
    tf: 1h
    enabled: true
    params:
      bb_window: 50
      k: 2.5
      sl_atr: 2.0
      max_bars: 24
```

Per aggiungere una strategia: nuova riga in `strategies.yml`, poi `docker compose restart`. Lo storico delle strategie esistenti rimane intatto.

### Persistenza

Ogni strategia ha la sua directory in `data/paper_trades/`:

```
data/paper_trades/
  MR01_bollinger_fade__BTC__1h/
    trades.jsonl    # Storico trade append-only
    status.json     # Stato corrente (resume al restart, include tp/sl/max_bars)
```

Notifiche Telegram per ogni trade (richiede `TELEGRAM_BOT_TOKEN` e `TELEGRAM_CHAT_ID` in `.env`).

## Setup

```bash
# Clona e installa
git clone <repo-url> && cd PythagorasGoal
uv sync

# Scarica dati storici (~70 MB)
uv run python -m src.data.downloader

# Backtest strategia attiva
uv run python scripts/strategies/MR01_bollinger_fade.py

# Paper trading live
uv run python -m src.live.multi_runner
```

### Requisiti

- Python ≥ 3.11
- [uv](https://docs.astral.sh/uv/) come package manager
- Accesso a Cerbero MCP (`cerbero-mcp.tielogic.xyz`) per dati Deribit live
- Docker (opzionale, per deploy su VPS)

## 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 |
| SOL / LTC / ADA | 1h | ~37K each | 2022 → oggi |

Fonte primaria: Deribit perpetual via Cerbero MCP. Fallback: Binance spot via ccxt. Formato: Apache Parquet.

### Discovery & validazione strumenti

`src/data/instruments.py` scopre e **valida** gli strumenti disponibili sugli
exchange implementati — **Deribit** e **Hyperliquid** (esclusi Alpaca/stocks e
**Bybit**, feed testnet inaffidabile). Ogni perpetuo viene testato sui dati
storici realmente raccoglibili: esistenza, congruenza OHLC, contratto non-morto,
liquidità e **congruenza prezzo cross-exchange** (mediana per base-coin, tolleranza
5%) — così feed farlocchi e contratti sbagliati (es. `SOL-PERPETUAL`=9.6) vengono
scartati. Il risultato è `data/instruments_registry.json` (strumenti validi +
timeframe + data d'inizio).

**Solo gli strumenti validati possono essere scaricati**: il downloader ha un gate
(`_download_cerbero_range`) che rifiuta quelli non nel registry. Rigenera con:

```bash
uv run python -m src.data.instruments
```

Simboli Deribit: BTC/ETH = `<COIN>-PERPETUAL` (inverse); altcoin =
`<COIN>_USDC-PERPETUAL` (lineari USDC). Registry attuale (testnet): Deribit 18/106
validi (major liquidi, BTC dal 2018), Hyperliquid 66/74.

## Riferimenti

- Serleto, L. & Malanga, C. — *Pythagoras Trading Prediction* (2024)
- Serleto, L. & Malanga, C. — *Libro dei Frattali* (2024)

## Licenza

Uso privato. Non destinato alla distribuzione.