From d02bc10ab59229341fda3bc8f13242313be51082 Mon Sep 17 00:00:00 2001 From: AdrianoDev Date: Fri, 29 May 2026 16:13:49 +0200 Subject: [PATCH] docs(portfolio): documenta cartella portfolios, comandi, scope live e default PORT06 Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 19 ++++++++++++++++++ README.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 70 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b7421ae..cd0f235 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -34,8 +34,15 @@ src/live/ → paper trading live multi-strategia cerbero_client.py → client HTTP per Cerbero MCP (Deribit testnet) signal_engine.py → squeeze + ML real-time (legacy ML01, ora in waste) + validazione OOS telegram_notifier.py → notifiche Telegram per trade +src/portfolio/ → portafogli di prima classe (capitale-pool, backtest+live) + base.py → SleeveSpec, Portfolio (.backtest), load_active_portfolio + weighting.py → schemi pesi: equal/cap/inverse_vol/cluster_rp/manual + sleeves.py → builder unificato equity-per-sleeve (fonte unica, parità report) + ledger.py → PortfolioLedger: capitale/PnL/DD/persistenza+resume + runner.py → PortfolioRunner live (data Cerbero v2, sizing, ribilancio) scripts/strategies/ → strategie con edge validato OOS: FADE (MR01/MR02/MR07), HONEST (DIP01/TR01/ROT02), PAIRS (PR01), TSMOM + portafogli (PORT01/02/03) +scripts/portfolios/ → definizioni PORT01-06 + report run() scripts/waste/ → strategie scartate (W01-W28 + famiglia squeeze SQ/MT/ML/AD/CM/PD) scripts/analysis/ → ricerca/validazione OOS fee-aware (strategy_research, oos_validation, ...) strategies.yml → config multi-strategy paper trader @@ -56,6 +63,9 @@ uv run python scripts/analysis/oos_validation.py # perche' la fami uv run python scripts/analysis/report_families.py # report per anno di tutte le famiglie uv run python scripts/analysis/validate_worker_pairs.py # replay worker 2 gambe == backtest uv run python -m src.live.multi_runner # paper trading live multi-strategia (strategie + pairs) +uv run python scripts/portfolios/PORT06_master_shape.py # report backtest portafoglio (default) +uv run python -m src.portfolio.runner # paper trading a PORTAFOGLIO (capitale pool) +uv run python scripts/analysis/smoke_portfolio.py # smoke live data layer Cerbero v2 docker compose up -d # deploy Docker uv run pytest # test ``` @@ -217,6 +227,15 @@ ma quei numeri sono backtest a leva 3x su 8 anni e includono anni eccezionali (e ETH 2024). Stima onesta: il target è *plausibile* su un portafoglio diversificato di queste fade, ma va confermato col paper trader live prima di rischiare capitale reale. +## Portafogli + +- Un `Portfolio` è un oggetto di prima classe (`src/portfolio/`) con definizione (sleeve + schema pesi) e due facce sulla **STESSA** definizione: `.backtest()` (riusa il builder unico di `sleeves.py` → parità esatta con `report_families`) e live (`PortfolioRunner`: capitale pool condiviso, sizing per peso, ribilancio giornaliero, ledger aggregato in `data/portfolios/{code}/`). +- **Schemi peso:** `equal` (default), `cap` (tetto per famiglia, es. pairs 33% — config raccomandata), `inverse_vol`, `cluster_rp` (equal fra cluster naturali poi inverse-vol intra-cluster), `manual`. Definiti in `weighting.py`; la chiave cap è la famiglia (PAIRS/FADE/HONEST/SHAPE/TSM). +- **Default `portfolios.yml`:** PORT06 (master+shape), `weighting=cap pairs 0.33`, leva 2x, ribilancio 1D. Backtest PORT06: FULL Sharpe 6.07 / OOS Sharpe 8.19, DD 4.9% full / 2.3% OOS. +- **Data layer Cerbero v2:** `get_historical_v2` unificato + `get_instruments` (naming robusto) + `get_ticker_batch`. Trading su Deribit. +- **SCOPE LIVE v1:** il runner esegue gli sleeve con worker pronti = fade (MR01/02/07) + pairs (PR01) + shape (SH01, via `MLWorkerWrapper` con retraining). Gli sleeve **honest (DIP01/TR01/ROT02) e TSM01 sono SALTATI nel live** (nessun worker dedicato ancora) → restano solo nel backtest; il runner li logga come saltati e rinormalizza i pesi sugli sleeve eseguibili. Worker honest/TSM01 = fase 2. +- **Limite noto:** al ribilancio le posizioni APERTE restano sul loro notional (non travasate); comportamento fedele al backtest daily-rebalanced entro il turnover infragiornaliero. + ## Multi-Strategy Paper Trader Orchestratore che esegue N strategie in parallelo su dati live Cerbero, ognuna con €1000 USDC virtuali indipendenti. diff --git a/README.md b/README.md index b34b448..3b84382 100644 --- a/README.md +++ b/README.md @@ -107,16 +107,23 @@ PythagorasGoal/ │ ├── 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 (strategie + pairs) -│ ├── strategy_worker.py # Worker single-leg con stato persistente -│ ├── pairs_worker.py # Worker a 2 gambe per i pairs (market-neutral) -│ ├── 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 +│ ├── live/ # Paper trading live su Deribit testnet +│ │ ├── multi_runner.py # Orchestratore multi-strategia (strategie + pairs) +│ │ ├── strategy_worker.py # Worker single-leg con stato persistente +│ │ ├── pairs_worker.py # Worker a 2 gambe per i pairs (market-neutral) +│ │ ├── 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 +│ └── portfolio/ # Portafogli di prima classe (capitale condiviso, backtest + live) +│ ├── base.py # SleeveSpec, Portfolio (.backtest), load_active_portfolio +│ ├── weighting.py # Schemi di ponderazione: equal, cap, inverse_vol, cluster_rp, manual +│ ├── sleeves.py # Builder unificato equity-per-sleeve (fonte unica, parità report) +│ ├── ledger.py # PortfolioLedger: PnL/DD aggregati, persistenza e resume +│ └── runner.py # PortfolioRunner live (Cerbero v2, sizing, ribilancio giornaliero) ├── scripts/ │ ├── strategies/ # Strategie con edge validato OOS (FADE, HONEST, PAIRS, TSMOM + portafogli) +│ ├── portfolios/ # Definizioni PORT01-06 e report run() dei portafogli di prima classe │ ├── waste/ # Strategie scartate (squeeze SQ/MT/ML/AD/CM/PD, MR03, ROT01, W01-W28) │ └── analysis/ # Ricerca/validazione OOS fee-aware, gestione rischio, report ├── strategies.yml # Config multi-strategy paper trader @@ -244,6 +251,42 @@ data/paper_trades/ Notifiche Telegram per ogni trade (richiede `TELEGRAM_BOT_TOKEN` e `TELEGRAM_CHAT_ID` in `.env`). +## Paper Trading a Portafoglio + +Accanto al multi-strategy runner originale — in cui ogni strategia gestisce autonomamente il proprio conto virtuale da €1.000 — il progetto dispone ora di un **paper trader a portafoglio** (`src/portfolio/`) che tratta l'insieme delle strategie come un unico organismo con un capitale condiviso. + +### Come funziona + +La definizione di un portafoglio (`SleeveSpec` + schema di peso) ha due facce sulla stessa sorgente dati: + +- **Backtest** (`.backtest()`): ricostruisce le equity-curve di ogni sleeve tramite il builder unificato in `sleeves.py`, le pondera secondo lo schema scelto e calcola le metriche aggregate (CAGR, Sharpe, max DD). La parità con i report prodotti da `report_families.py` è garantita dalla fonte unica. +- **Live** (`PortfolioRunner`): ogni ora il runner scarica le candele aggiornate via Cerbero v2, calcola i pesi correnti, avvia i worker appropriati per ogni sleeve attiva e registra il PnL aggregato nel ledger (`data/portfolios/{code}/`). Il ledger persiste tra i riavvii. + +### Schemi di ponderazione + +Il modulo `weighting.py` mette a disposizione cinque schemi: `equal` (default), `cap` (tetto per famiglia — p.es. `pairs: 0.33` per limitare la concentrazione), `inverse_vol` (pesi inversamente proporzionali alla volatilità storica), `cluster_rp` (equal tra cluster naturali poi inverse-vol all'interno del cluster) e `manual` (pesi liberi). Lo schema si specifica in `portfolios.yml` insieme al codice portafoglio e alla leva. + +### Portafoglio di default: PORT06 + +La configurazione raccomandata è **PORT06** (`scripts/portfolios/PORT06_master_shape.py`): portafoglio master esteso che include tutte e sei le famiglie (FADE, HONEST, PAIRS, TSMOM, SHAPE), con schema `cap` che limita i pairs al 33% del capitale per moderare la loro concentrazione di rischio. Risultati del backtest: Sharpe 6.07 (FULL) / 8.19 (OOS), drawdown massimo 4.9% (FULL) / 2.3% (OOS), leva 2×. + +### Scope live (v1) + +Il runner esegue le famiglie per cui esiste un worker dedicato: **fade** (MR01, MR02, MR07), **pairs** (PR01, cinque coppie) e **shape** (SH01, con retraining periodico via `MLWorkerWrapper`). Le famiglie **honest** (DIP01, TR01, ROT02) e **TSMOM** (TSM01) sono al momento escluse dall'esecuzione live — restano nel backtest — e il runner lo segnala nel log, rinormalizzando automaticamente i pesi sugli sleeve attivi. Il supporto ai worker honest e TSM01 è previsto nella fase 2. + +### Avvio del paper trader a portafoglio + +```bash +# Backtest del portafoglio di default (PORT06) +uv run python scripts/portfolios/PORT06_master_shape.py + +# Paper trading live a portafoglio +uv run python -m src.portfolio.runner + +# Smoke test del data layer Cerbero v2 +uv run python scripts/analysis/smoke_portfolio.py +``` + ## Setup ```bash