diff --git a/docs/reports/2026-05-14-stato-progetto-e-roadmap.md b/docs/reports/2026-05-14-stato-progetto-e-roadmap.md new file mode 100644 index 0000000..c5e9ff2 --- /dev/null +++ b/docs/reports/2026-05-14-stato-progetto-e-roadmap.md @@ -0,0 +1,287 @@ +# Multi-Swarm Coevolutivo — Stato del progetto e roadmap + +*Data del documento: 14 maggio 2026 — branch `main` allineato a commit `45f273f`.* + +Questo documento riepiloga l'intero percorso del proof-of-concept Multi-Swarm Coevolutive dalla Phase 1 (lean spike) fino allo stato corrente di entrata in Phase 3 (paper-trading forward-test). È inteso come punto di sincronizzazione per riprendere il lavoro: cosa è stato deciso, cosa ha funzionato, cosa no, e quali sono le prossime mosse plausibili. + +--- + +## 1. Quadro sintetico + +| Fase | Periodo | Stato | Esito | +|------|---------|-------|-------| +| **Phase 1** — lean spike | 9-10 maggio 2026 | ✅ chiusa | GO Phase 2 (5/5 hard gate) | +| **Phase 1.5** — adversarial hardening | 11 maggio 2026 | ✅ chiusa | NO-GO sulla combo nemotron, hardening conservato | +| **Phase 2** — feature temporali + qwen3-235b | 11 maggio 2026 | ✅ chiusa | NO-GO sul modello (rollback a qwen-2.5-72b) | +| **Phase 2.5** — LLM prompt mutator | 11-12 maggio 2026 | ✅ chiusa | Operator integrato, sweet spot weight 0.20-0.30 | +| **Phase 2.6** — Walk-Forward Validation | 12-13 maggio 2026 | ✅ chiusa | WFA 70/30 introdotta, min-trades parametrico | +| **Phase 2.7** — portabilità cross-asset (BTC/ETH/SOL) | 13 maggio 2026 | ✅ chiusa | BTC strong, ETH adequate, SOL failure | +| **Phase 3** — paper-trading forward-test | 13-14 maggio 2026 | 🟢 in corso | Runner BTC+ETH operativo, smoke OK | + +Dal punto di vista del DB locale: 30 run GA completate, costo cumulato LLM **≈ $3.74**, due paper-trading run avviati (`phase3-smoke-001`, `phase3-papertrade-001`). + +--- + +## 2. Phase 1 — lean spike (chiusa 10 maggio) + +### Obiettivo +Validare end-to-end l'idea co-evolutiva: GA → popolazione di prompt LLM → strategie JSON → backtest deterministico → fitness → selezione. Cinque hard gate vincolanti. + +### Risultato +Run di riferimento `phase1-real-005` su BTC-PERPETUAL Deribit 1h, 2024-01-01 → 2026-01-01, K=20, 10 generazioni, **costo $0.069 in 29 minuti**. + +| Hard gate | Soglia | Misurato | Esito | +|-----------|--------|----------|-------| +| Loop convergence | median sale | 0.0001 → 0.0188 in 3 gen | ✓ | +| Parse success | ≥ 95% | 100% (98/98) post refactor JSON | ✓ | +| Top-5 vs median | ≥ 10× | 1116× | ✓ | +| Entropy fitness gen 9 | ≥ 0.5 | 0.914 | ✓ | +| Costo totale | ≤ $700 | $0.069 | ✓ | + +Iterazione: 5 run prima del PASS, ognuna ha scoperto un bug strutturale (max_dd su equity assoluta, cap Cerbero 5000 candele, validator arity, switch grammar S-expr→JSON, fitness clip-to-0 troppo dura). + +### Caveat critico +Il top-1 ha reso **+2.66% in 2 anni vs B&H BTC +106%**, essendo *flat* nel 99,8% del tempo. Conferma che la fitness v1 premiava "non-strategie" sicure invece di alpha vero. Da qui la Phase 1.5. + +### Documenti chiave +- `docs/decisions/2026-05-10-gate-phase1.md` — decision memo. +- `docs/reports/2026-05-10-phase1-technical-report.md` — report tecnico. + +--- + +## 3. Phase 1.5 — adversarial hardening (chiusa 11 maggio) + +Quattro nuovi check `HIGH` aggiunti all'agente Adversarial per killare strategie degeneri: + +1. `overtrading` ricalibrato `n_bars/20` (era `n_bars/5`). +2. `undertrading` promosso a HIGH se `n_trades < 10`. +3. `flat_too_long` (nuovo HIGH) — segnale flat > 95% bar. +4. `fees_eat_alpha` (nuovo HIGH) — `fees / |gross_pnl| > 0.5` con gross positivo. +5. `time_in_market_too_high` (nuovo HIGH) — segnale LONG||SHORT > 80% bar (kill leveraged-B&H camuffato). + +**Run di test `phase1.5-nemotron-001`** (tier C nemotron, 2h26', $0.12) → **NO-GO**: max fitness 0.0215 stagnante, median 0 su 9 gen, top-5 con DSR=0 e Sharpe ≈ −1.1. I check Phase 1.5 funzionavano (98 findings emessi); il problema era il modello: prompt calibrato su qwen, nemotron produceva materiale qualitativamente più povero. + +Bugfix collaterale (`9d0deb3`): `EmptyCompletionError` reso retryable + gestione `resp.usage=None` per provider `:free`. + +--- + +## 4. Phase 2 — feature temporali + tier C qwen3-235b (chiusa 11 maggio) + +Due lavori in parallelo, esiti opposti: + +**4.1 Feature temporali in protocol layer** — `KNOWN_FEATURES` esteso con `hour`, `dow`, `is_weekend`, `minute_of_hour`. Compiler dispatcher temporale (`9d1f97c`), validator parametrizzato, integration test gating temporale+SMA. Few-shot example nel prompt Hypothesis. **Successo strutturale**: tutte le top strategie successive sfruttano questo asset. + +**4.2 Upgrade tier C a `qwen/qwen-2.5-72b-instruct` → `qwen3-235b-a22b`** — run `phase2-qwen3-001`: max fitness 0.0238 stuck per 8 gen, entropy 0.199 stuck per 7 gen, 4 dei 5 top genomi con fitness/Sharpe/DD identici. Il **run controllo** identico ma con qwen-2.5-72b: 0.0311 (+30%), median raggiunge top in 4 gen, entropy 0.85, ½ tempo e costo. **Rollback a qwen-2.5-72b** (`8ec45c5`). + +Lezione consolidata: il prompt è calibrato sulla famiglia qwen-2.5; un modello "più nuovo / più grande" non è automaticamente meglio se il prompt non viene ricalibrato in parallelo. + +--- + +## 5. Phase 2.5 — operator `mutate_prompt_llm` (chiusa 12 maggio) + +Quinto operatore di mutazione che riscrive il `system_prompt` via LLM tier B (`deepseek-v4-flash`) anziché perturbare scalari. Sei istruzioni atomiche: `tighten_threshold`, `swap_comparator`, `add_condition`, `remove_condition`, `change_timeframe`, `add_temporal_gate`. Validation gate (lunghezza ≥ 50, keyword tecnica, diff Levenshtein > 5%) + fallback `random_mutate`. Dispatcher pesato `weighted_random_mutate` (CLI `--prompt-mutation-weight`, default 0.0). + +### Sweet spot empirico (seed 42, pop 20, 10 gen) + +| weight | max fit | median fin | Sharpe top | trades | verdetto | +|--------|---------|-----------|-----------|--------|----------| +| 0.00 | 0.0311 | 0.0000 | −1.08 | 274 | baseline | +| **0.30** | **0.1012** ⭐ | **0.0745** | **−0.25** | 62 | sweet spot (ma seed-lucky) | +| 0.50 | 0.0311 | 0.0000 | −1.08 | 274 | regressione | + +### Validazione robustezza +Confronti seed multipli (7, 99, 123) hanno mostrato che il **+225%** del run 004 era **outlier seed-specific**. Beneficio medio reale del prompt-mutator: **+10–23%** sopra baseline. La leva più affidabile e seed-indipendente è risultata `fees_eat_alpha_threshold 0.7` (anziché 0.5): +23% stabile, Sharpe top −0.70 vs −1.08. + +### Combo vincente (pop=30 + weight=0.30 + fees=0.7) +Run `pop30-combo-001`: max fitness 0.0459 (+48% vs control), **median finale = max** (convergenza ≥50% pop), Sharpe top −0.63, 226 trades. Mutator overhead ≈ 5,4% del costo totale. + +### Cost attribution (Task 6) +`cost_records.call_kind` (`hypothesis` / `mutation`) attivo da `ba4eb09`. Permette breakdown costo per operatore: il prompt-mutator costa 3-9% del totale, trascurabile. + +--- + +## 6. Phase 2.6 — Walk-Forward Validation (chiusa 13 maggio) + +Aggiunte tre leve metodologiche: + +- **WFA 70/30**: split temporale `train/OOS` con OOS intoccato durante GA, valutato solo a fine run. +- **`--min-trades-threshold`** parametrico: filtra survivors con n_trades insufficiente prima del ranking. +- **Fitness v2 soft-kill** (`cf42dd8`): solo `no_trades` + `degenerate` + `undertrading` azzerano hard. Altri HIGH applicano penalty moltiplicativa `1/(1+0.4·n)` (1 HIGH = 0,71×, 2 = 0,56×, 3 = 0,45×). CLI `--fitness-v2` + `--fitness-soft-penalty`. +- **Pattern guidance nel system prompt** (`67ae6ff`): forma curve attese + criterio ripetibilità. +- **Fitness multi-obiettivo** (`1a1dfb7`): `combined = α·IS + (1−α)·OOS` opt-in. + +Effetto cumulativo: la pipeline produce strategie con migliore generalizzazione cross-split senza dover degradare le adversarial hard. + +--- + +## 7. Phase 2.7 — backtest 7 anni e portabilità cross-asset (chiusa 13 maggio) + +### 7.1 Validazione 7,33 anni su BTC + +Backtest dei top genome scoperti sulle varie sotto-fasi sui **64.297 bar 1h** completi (2018-09-01 → 2026-01-01), fees 5 bp: + +| Genome | Origine | Total P/L 7y | CAGR | Sharpe ann | MaxDD | Verdetto | +|--------|---------|--------------|------|-----------|-------|----------| +| `5226503a` | run004 outlier 2y bull | **−310,69%** | wiped out | −0,155 | 280,9% | crash totale OOS | +| `e52604ba` | flat-ablation top 2y | −37,17% | −6,14% | −0,063 | 182,0% | SMA non generalizza | +| `ec06a3d4` | fitness-v2-combo top 2y | +142,51% | +12,85% | +0,229 | 64,9% | hour-gated regge | +| `4e1be9fa` | 7y-v2-WFA top IS | +67,60% | +7,30% | +0,240 | 79,1% | top IS ingannevole | +| `63411199` | 7y-v2-WFA top OOS | **+660,11%** | **+31,88%** | +0,238 | 77,1% | leveraged-B&H camuffato | +| **`fb63e851`** ⭐ | 7y multi-seed99 top OOS | +130,37% | +12,06% | **+0,264** | **54,8%** | **true alpha** | + +Conclusioni: +- Il top by `fit_IS` è sistematicamente ingannevole su orizzonti lunghi. +- Pattern SMA-puri collassano cross-regime. +- Pattern *hour-gated* (filtri intraday) reggono cross-regime. +- `fb63e851` è il candidato più robusto: 4 AND × 2 rule × filtro intraday → attiva l'1-2% del tempo, Sharpe cross-regime più alto. + +### 7.2 Portabilità BTC → ETH → SOL + +Tre run **identici** (`population=30`, `n_gen=10`, `prompt_mutation_weight=0.30`, fitness v2, WFA 70/30, `fees_eat_alpha_threshold=0.7`, undertrading 20) su Deribit perpetuals. + +| Asset | Storia | Top OOS Sharpe | Verdetto | +|-------|--------|----------------|----------| +| **BTC** | 7,33 y | `fb63e851` +0,50 OOS (+20,16%) | **STRONG** | +| **ETH** | 6,75 y | `facd6af85d5d` +0,19 OOS (+16,14%) | **ADEQUATE** | +| **SOL** | 3,00 y | **0 survivors / 247 evals** | **FAILURE** | + +Pattern scoperti **divergenti**: BTC = mean reversion intraday contrarian; ETH = trend-following long-bias + vol regime. **Non esiste "una strategia universale"**: la metodologia (GA + WFA + adversarial v2) è portabile, il pattern no. SOL ha fallito per finestra dati troppo corta (3y) e regime bull-only post-FTX. + +--- + +## 8. Phase 3 — paper-trading forward-test (in corso) + +### Componenti implementati (`45f273f`) + +Modulo `src/multi_swarm/paper_trading/`: +- `portfolio.py` — multi-asset portfolio con sleeve uguali per asset, fees in bp. +- `executor.py` — `PaperExecutor` carica una strategia JSON, compila, valuta l'ultimo bar. +- `persistence.py` — `PaperRepository` su SQLite (tabelle `paper_trading_runs`, `paper_trading_ticks`, `paper_trading_equity`, `paper_trading_trades`, `paper_trading_positions`). + +Runner `scripts/run_paper_trading.py`: +- Loop poll OHLCV Cerbero ogni `--poll-seconds` (default 300). +- Riconosce *nuovo bar chiuso* confrontando ultimo timestamp; tick consecutivi su stesso bar = hold. +- Snapshot equity ogni tick. +- Supporta `--max-ticks N` per smoke test (0 = infinito). + +Strategie freezate per il forward-test: +- `strategies/btc_fb63e851.json` — RSI estremi + ATR vs SMA + filtro orario 9-17. +- `strategies/eth_facd6af85d5d.json` — ATR + realized_vol + golden/death cross. + +### Stato corrente +- Schema DB esteso e validato. +- Run smoke completato (`phase3-smoke-001`). +- Run live in corso (`phase3-papertrade-001`). + +--- + +## 9. Architettura cumulata + +``` +src/multi_swarm/ +├── config.py +├── data/{cerbero_ohlcv,splits}.py ← splits.py per WFA +├── backtest/{orders,engine}.py +├── metrics/{basic,dsr,diversity}.py ← diversity per Phase 2.5 +├── cerbero/{client,tools}.py +├── protocol/{grammar,parser,validator,compiler}.py +│ └── KNOWN_FEATURES include hour/dow/is_weekend/minute_of_hour +├── genome/ +│ ├── hypothesis.py +│ ├── mutation.py ← 4 operatori scalari +│ ├── mutation_prompt_llm.py ← Phase 2.5: 5° operatore LLM +│ └── crossover.py +├── llm/{client,cost_tracker}.py ← cost_kind tracking +├── agents/{hypothesis,falsification,adversarial,market_summary}.py +│ └── adversarial: 5 check HIGH parametrici (CLI knobs) +├── ga/ +│ ├── selection.py +│ ├── fitness.py ← v1 + v2 soft-kill + combined IS/OOS +│ ├── loop.py +│ ├── summary.py +│ └── initial.py +├── persistence/{schema,repository}.py ← +tabelle paper_trading_* +├── paper_trading/ ← NEW Phase 3 +│ ├── portfolio.py +│ ├── executor.py +│ └── persistence.py +├── orchestrator/run.py +└── dashboard/ + ├── streamlit_app.py + pages/ ← legacy 8501 + ├── nicegui_app.py (880 LOC) ← port progressivo 8080 + ├── aquarium.py + data.py +``` + +CLI knobs accumulati per ablation: +- `--prompt-mutation-weight FLOAT` (Phase 2.5) +- `--fees-eat-alpha-threshold FLOAT` (default 0.5, suggerito 0.7) +- `--flat-too-long-threshold FLOAT` (default 0.95) +- `--undertrading-threshold INT` (default 20) +- `--fitness-v2` + `--fitness-soft-penalty FLOAT` +- `--fitness-combined-alpha FLOAT` (multi-obiettivo IS/OOS) +- `--min-trades-threshold INT` (WFA OOS filter) + +--- + +## 10. Cosa resta da fare + +### 10.1 Phase 3 — completamento paper-trading +- [ ] **Definire criterio di STOP/GO Phase 3**: durata minima forward-test (es. 4-8 settimane), soglie sopravvivenza (Sharpe live > 50% del Sharpe OOS atteso, DD live < 1,5× DD OOS). +- [ ] **Pagina dashboard paper-trading**: estendere NiceGUI con tab live equity + open positions + tick log per `paper_trading_runs`. Oggi i dati esistono in DB ma non hanno UI dedicata. +- [ ] **Monitoring & alerting**: notifica se il runner si ferma (Cerbero down, processo killato). Considerare systemd unit o supervisor. +- [ ] **Robustezza fetch live**: oggi `loader._fetch(req)` bypassa la cache; aggiungere retry esplicito (oltre a quello tenacity già presente nel client) e log strutturato dei fallimenti per asset. +- [ ] **Confronto live vs OOS atteso**: script che a fine settimana confronta P/L, Sharpe rolling, hit rate vs i numeri del backtest 7y per individuare *regime mismatch* precoce. + +### 10.2 Estensioni metodologiche +- [ ] **Multi-seed ensembling**: invece di scegliere un singolo top genome, valutare ensemble (mediana o weighted) dei top-K trovati con seed diversi sullo stesso asset. La varianza seed è il rischio numero uno (vedi sezione 5). +- [ ] **Asset universe expansion**: testare la metodologia su asset non-crypto (oro, forex EURUSD) per smentire l'ipotesi che funzioni solo perché BTC/ETH hanno alta volatilità. `yfinance` è già in dipendenze (`9d1ef8a`). +- [ ] **Fitness regime-aware**: oggi fitness è single-objective sull'intero train. Considerare fitness condizionata al regime (bull/bear/range) per favorire strategie con performance bilanciata cross-regime invece di top assoluto. +- [ ] **Phase 2.7 retry su SOL** con configurazione mirata: train più corto, undertrading_threshold ridotto, prompt few-shot di strategie short-vol-only. Verificare se è davvero il dato a fallire o se è la calibrazione. + +### 10.3 Hardening tecnico +- [ ] **Cleanup zombie runs**: `phase2-6-flat-wfa-001` è ancora `failed` nel DB. Verificare che il flush di stato sia idempotente per tutti i path di crash. +- [ ] **Port completo dashboard a NiceGUI**: oggi convivono Streamlit (8501) e NiceGUI (8080). Manca su NiceGUI la pagina **Aquarium** (canvas HTML5 con pesci animati per agente). Una volta portata, deprecare Streamlit. +- [ ] **Pruning DB**: dopo 30+ run la SQLite cresce. Aggiungere uno script di archiviazione/compressione delle run completate più vecchie di N giorni. +- [ ] **CI/test coverage**: i 180+ test girano localmente; non c'è ancora CI esterna (Gitea Actions o equivalente). + +### 10.4 Documentazione e governance +- [ ] **Decision memo Phase 2.5 + Phase 2.6 + Phase 2.7** formalizzati come `docs/decisions/2026-05-1{2,3}-*.md` (esistono solo memory + commit message; manca il pendant pubblico dei due memo già esistenti per Phase 1 e Phase 1.5). +- [ ] **Phase 3 charter**: documento che fissa a priori cosa significherà "successo" o "fallimento" del forward-test, per evitare *moving goalposts* a posteriori. +- [ ] **Threats to validity update**: il memo Phase 1 ne elencava 6; integrarli con le scoperte successive (varianza seed, portabilità asset-specifica, divergenza pattern BTC/ETH). + +--- + +## 11. Caveat e rischi aperti + +1. **Varianza seed**: con seed diversi (7, 99, 123) sullo stesso identico setup il max fitness varia di un fattore 3-4×. Qualunque metrica single-seed è statisticamente debole; finché Phase 3 non raccoglie N≥5 forward-test indipendenti, il vantaggio del prompt-mutator resta nel rumore. +2. **Sharpe OOS positivi ma bassi**: BTC `+0,50` ed ETH `+0,19` sono migliori del coin-flip ma lontani dai target retail "investment-grade" (≥ 1,0). La metodologia è validata, l'alpha catturata è modesta. +3. **`time_in_market_too_high` come red-flag chiave**: `63411199` ha CAGR +31,88% ma esposizione 90% del tempo — è leveraged-B&H camuffato, non alpha. Phase 3 deve preferire `fb63e851` (selettività 1-2%) anche se ha return assoluto minore. +4. **Dipendenza dal modello qwen-2.5-72b**: rollback Phase 2 ha dimostrato che il prompt è calibrato su questa specifica famiglia. Se il modello venisse deprecato da OpenRouter, sarebbe necessario un giro di ricalibrazione prompt → rischio di operatività. +5. **Cerbero MCP come single point of failure**: tutti i fetch OHLCV passano da lì. Da considerare un fallback (ccxt o yfinance) almeno per il paper-trading. + +--- + +## 12. Costi cumulati + +- **Phase 1 (5 run iterazione)**: $0,19. +- **Phase 1.5 nemotron**: $0,12. +- **Phase 2 + 2.5 + 2.6 + 2.7**: ≈ $3,24 cumulati su 25+ run. +- **Totale LLM progetto a oggi**: ≈ **$3,74** (DB locale). +- **Phase 3 paper-trading**: $0 incrementali per LLM (le strategie sono fisse), solo costi Cerbero (incluso nel servizio esistente). + +Resta amplissimo margine rispetto al cap originale Phase 1 di $700. + +--- + +## 13. Riferimenti + +- README.md — overview e setup. +- `docs/decisions/2026-05-10-gate-phase1.md`, `docs/decisions/2026-05-11-phase1-5-nemotron-run.md`. +- `docs/reports/2026-05-10-phase1-technical-report.md`. +- `docs/superpowers/specs/2026-05-09-decisione-strategica-design.md`, `docs/superpowers/specs/2026-05-11-temporal-features-design.md`. +- `docs/superpowers/plans/2026-05-09-phase1-lean-spike.md`, `docs/superpowers/plans/2026-05-11-mutate-prompt-llm-phase-2-5.md`, `docs/superpowers/plans/2026-05-11-temporal-features.md`. +- DB locale `runs.db` per dettaglio run-by-run. + +--- + +*Prossimo checkpoint suggerito: rivedere questo documento al termine del primo ciclo completo di Phase 3 (≥ 2 settimane di forward-test continuo) per consolidare i risultati live e decidere GO/NO-GO verso un eventuale Phase 4 (capitale reale ridotto o estensione del universe).*