# 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

```bash
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:

```python
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.