docs: README.md e CLAUDE.md con documentazione progetto completa

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-27 08:04:21 +02:00
parent c44f008e4d
commit 1617330d10
2 changed files with 194 additions and 0 deletions
@@ -0,0 +1,74 @@
+# 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
+
+```bash
+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:
+
+```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.
+
+## 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.