diff --git a/docs/decisions/2026-05-10-gate-phase1.md b/docs/decisions/2026-05-10-gate-phase1.md new file mode 100644 index 0000000..ecce167 --- /dev/null +++ b/docs/decisions/2026-05-10-gate-phase1.md @@ -0,0 +1,169 @@ +# Gate Phase 1 — Decision Memo + +**Data**: 10 maggio 2026 +**Run analizzati**: phase1-real-001 (in attesa di completamento; eventuali run successivi listati qui) +**Spesa totale Phase 1**: $TBD di $700 cap (=TBD%) +**Tempo speso Phase 1**: TBD settimane (calendar) +**Status**: TEMPLATE — completare con numeri reali a fine run. + +--- + +## 1. Premessa + +Questo memo formalizza la valutazione dei 5 hard gate definiti nello spec strategico (`docs/superpowers/specs/2026-05-09-decisione-strategica-design.md`, sez. 4.4) sulla base dei risultati della/e run reale/i. Segue la regola "mai self-approve": **author pass** seguito da **review pass adversarial** prima della decisione formale. + +I gate sono numerici per costruzione: PASS o FAIL è meccanico, non discrezionale. Discrezionale è solo l'azione successiva quando uno o più gate falliscono. + +--- + +## 2. Author pass — valutazione hard gate + +### Gate 1 — Loop converge + +**Soglia**: la fitness mediana della popolazione cresce per ≥3 generazioni consecutive prima di plateau. + +**Misura osservata**: + +| Generazione | Median fitness | Variazione | +|---|---|---| +| 0 | TBD | — | +| 1 | TBD | TBD | +| 2 | TBD | TBD | +| 3 | TBD | TBD | +| 4 | TBD | TBD | +| 5 | TBD | TBD | +| 6 | TBD | TBD | +| 7 | TBD | TBD | +| 8 | TBD | TBD | +| 9 | TBD | TBD | + +Numero di generazioni consecutive con crescita: **TBD**. + +**Esito**: PASS / FAIL + +**Razionale**: TBD. + +--- + +### Gate 2 — Output formalizzabile + +**Soglia**: ≥80% delle proposte LLM passano il parser S-expression senza intervento manuale. + +**Misura osservata**: +- Evaluations totali: TBD +- Parse success: TBD (= TBD%) +- Parse error: TBD + +Distribuzione errori più frequenti: +- TBD + +**Esito**: PASS / FAIL + +**Razionale**: TBD. + +--- + +### Gate 3 — Tail superiore + +**Soglia**: i top-5 genomi hanno DSR in-sample ≥ 1.5x la mediana di popolazione. + +**Misura osservata**: +- Median DSR popolazione: TBD +- Top-5 DSR: TBD, TBD, TBD, TBD, TBD +- Top-5 mediano: TBD +- Ratio (top-5 mediano / pop median): TBD + +**Esito**: PASS / FAIL + +**Razionale**: TBD. + +--- + +### Gate 4 — Diversità non collassa + +**Soglia**: entropia della distribuzione di fitness in popolazione > 0.5 a fine run. + +**Misura osservata**: +- Entropy generazione finale: TBD +- Entropy iniziale (gen 0): TBD +- Trend entropy: TBD + +**Esito**: PASS / FAIL + +**Razionale**: TBD. + +--- + +### Gate 5 — Cost predictability + +**Soglia**: spesa effettiva entro ±30% della stima preventivata ($500-700 per Phase 1). + +**Misura osservata**: +- Stima preventivo: $500-700 (mid $600) +- Spesa reale: $TBD (somma `total_cost_usd` su tutti i run Phase 1) +- Deviazione: TBD% + +**Esito**: PASS / FAIL + +**Razionale**: TBD. + +--- + +## 3. Soft observations (informative, non vincolanti) + +- **Diversità cognitiva**: cognitive_style sopravvissuti a fine run: TBD su 6 originali. +- **Top-5 ispezione qualitativa**: i top genomi propongono strategie strutturalmente diverse o sono cloni? TBD. +- **Failure mode parser**: tassonomia degli errori parse dominanti (TBD). +- **Cerbero/Deribit data quality**: gap nei dati storici, anomalie. TBD. + +--- + +## 4. Author pass — conclusione + +**Esito complessivo author pass**: PASS / FAIL / PARTIAL + +Hard gate falliti (se presenti): TBD. + +**Decisione raccomandata dall'autore**: +- [ ] GO Phase 2 (specificare aggiustamenti) +- [ ] ITERATE Phase 1 (specificare cosa cambiare prima di un nuovo run) +- [ ] PIVOT (specificare dominio o approach alternativo) +- [ ] STOP (specificare razionale + learnings) + +**Razionale autore**: TBD. + +--- + +## 5. Review pass — red team adversarial + +**Modalità review pass**: subagent Claude red-team / collega umano / fresh-eyes 48h. *(Selezionare e documentare).* + +**Critiche strutturate ricevute**: + +1. **Cherry-picking**: i numeri sopra sono stati cherry-picked? Quali run sono stati esclusi e perché? TBD. +2. **Statistical robustness**: i gate basati su DSR usano `n_trials` corretto? Bonferroni applicato? TBD. +3. **Overfitting al training**: c'è hold-out genuino o tutta la valutazione è in-sample? TBD. +4. **Diversità apparente vs reale**: signal correlation fra top-5 misurata? Possono essere cloni che hanno solo prompt diversi? TBD. +5. **Cost trap**: la spesa è entro budget ma vicina al cap? Estrapolando linearmente, Phase 2 sfora? TBD. + +**Contro-evidenze raccolte / fix applicati**: +- TBD. + +--- + +## 6. Decisione finale + +**Decisione**: [GO Phase 2 | ITERATE Phase 1 | PIVOT | STOP] + +**Razionale finale (post-review)**: TBD. + +**Aggiustamenti per la fase successiva**: +- TBD. + +**Documenti correlati prodotti**: +- `docs/reports/2026-05-10-phase1-technical-report.md` (report tecnico ~5 pagine) +- `docs/runs/2026-05-10-phase1-real-001.md` (per ogni run, da creare se serve) + +--- + +*Memo da committare insieme al report tecnico Phase 1. Versione 1.0 del template — popolare con dati reali a chiusura run.* diff --git a/docs/reports/2026-05-10-phase1-technical-report.md b/docs/reports/2026-05-10-phase1-technical-report.md new file mode 100644 index 0000000..4df24d0 --- /dev/null +++ b/docs/reports/2026-05-10-phase1-technical-report.md @@ -0,0 +1,222 @@ +# Phase 1 Lean Spike — Rapporto Tecnico + +**Autore**: Adriano Dal Pastro +**Data**: 10 maggio 2026 +**Versione**: 1.0 (TEMPLATE — popolare con dati a chiusura run) +**Status**: in attesa risultati run reale (`phase1-real-001` in corso) + +**Documenti correlati**: +- `docs/superpowers/specs/2026-05-09-decisione-strategica-design.md` (decisione strategica) +- `docs/superpowers/plans/2026-05-09-phase1-lean-spike.md` (piano implementativo) +- `docs/decisions/2026-05-10-gate-phase1.md` (decision memo gate) + +--- + +## 1. Setup sperimentale + +**Obiettivo della Phase 1 lean spike**: dimostrare che il loop tecnico funziona end-to-end. Non è una valutazione dell'edge alpha, è una validazione di fattibilità. I cinque hard gate dello spec sez. 4.4 misurano se il sistema gira come progettato e se l'output LLM è formalizzabile, non se le strategie generate sarebbero profittevoli. + +### 1.1 Configurazione del run + +| Parametro | Valore | +|---|---| +| Population size (K) | 20 | +| Generazioni | 10 | +| Elite k | 2 | +| Tournament k | 3 | +| Crossover probability | 0.5 | +| Random seed | 42 | +| Symbol | BTC-PERPETUAL (Deribit) | +| Timeframe | 1h | +| Range storico | 2024-01-01 → 2026-01-01 (2 anni) | +| Fees backtest | 5 basis points | +| n_trials_dsr | 50 | +| Tier LLM dominante | C (qwen3-235b-a22b-2507 via OpenRouter) | +| Cerbero MCP endpoint | http://localhost:9001 (locale) | + +### 1.2 Stack tecnologico + +Python 3.13, uv, pytest+pytest-mock+responses, sqlmodel/sqlite per persistence, sexpdata per parsing, pandas+numpy+scipy per analytics, openai SDK con base URL OpenRouter, tenacity per retry transient, streamlit+plotly per dashboard. + +### 1.3 Architettura del run + +L'orchestrator (`src/multi_swarm/orchestrator/run.py`) coordina la pipeline end-to-end: caricamento OHLCV via `CerberoOHLCVLoader` (cache parquet), costruzione market summary, popolazione iniziale di K=20 genomi diversificati per cognitive_style (6 stili: physicist, biologist, historian, meteorologist, ecologist, engineer), e per ogni generazione il loop hypothesis (LLM call, parse S-expression) → falsification (compile, backtest, DSR) → adversarial (heuristic checks) → fitness (DSR − dd_penalty * max_dd, kill su HIGH adversarial finding) → next_generation (elitism + tournament + crossover/mutation). Tutti gli stati sono persistiti su SQLite (`runs.db`) con indici su fitness desc per query rapide della dashboard. + +### 1.4 Caveat metodologici + +- **In-sample**: il backtest in Phase 1 lean spike non usa walk-forward; tutto il range 2024-2026 viene usato sia per la generazione delle ipotesi sia per la loro valutazione. La sopravvivenza out-of-sample è esplicitamente fuori scope di Phase 1 (gate Phase 2 #2). +- **Compiler con indicatori built-in**: il compiler S-expression (`src/multi_swarm/protocol/compiler.py`) calcola RSI, SMA, ATR, MACD, realized_vol localmente con pandas. `CerberoTools` è plumbed ma non chiamato durante l'esecuzione delle strategie — è disponibile come tool per agenti future-tense ma il fitness in Phase 1 dipende solo dagli indicatori locali. +- **Mock RSI epsilon**: il compiler ha un epsilon-floor su `roll_down` per evitare RSI = 100 esatto su serie monotonicamente crescenti (artefatto matematico irrilevante su dati reali ma documentato). + +--- + +## 2. Loop convergence + +**Domanda gate 1**: la popolazione converge nel tempo? + +### 2.1 Fitness per generazione + +| Gen | Median | Max | P90 | Entropy | +|---|---|---|---|---| +| 0 | TBD | TBD | TBD | TBD | +| 1 | TBD | TBD | TBD | TBD | +| 2 | TBD | TBD | TBD | TBD | +| 3 | TBD | TBD | TBD | TBD | +| 4 | TBD | TBD | TBD | TBD | +| 5 | TBD | TBD | TBD | TBD | +| 6 | TBD | TBD | TBD | TBD | +| 7 | TBD | TBD | TBD | TBD | +| 8 | TBD | TBD | TBD | TBD | +| 9 | TBD | TBD | TBD | TBD | + +### 2.2 Plot + +*(Inserire screenshot dashboard — pagina GA Convergence — `docs/reports/figures/phase1/ga-convergence.png`)* + +### 2.3 Osservazioni + +- Generazioni di crescita consecutiva mediana: TBD. +- Plateau osservato a partire dalla generazione: TBD. +- Entropy a fine run: TBD (gate threshold 0.5). + +--- + +## 3. Top-5 genomi: ispezione qualitativa + +**Domanda gate 3**: il tail superiore della popolazione esiste e separa segnale da rumore? + +| Rank | Genome ID (short) | Fitness | DSR | Sharpe | Max DD | Trades | Cognitive style | Tier | +|---|---|---|---|---|---|---|---|---| +| 1 | TBD | TBD | TBD | TBD | TBD | TBD | TBD | TBD | +| 2 | TBD | TBD | TBD | TBD | TBD | TBD | TBD | TBD | +| 3 | TBD | TBD | TBD | TBD | TBD | TBD | TBD | TBD | +| 4 | TBD | TBD | TBD | TBD | TBD | TBD | TBD | TBD | +| 5 | TBD | TBD | TBD | TBD | TBD | TBD | TBD | TBD | + +### 3.1 Strategie selezionate + +Per ognuno dei top-5, riportare la S-expression generata e una lettura qualitativa: il pattern catturato è economicamente plausibile (es. mean reversion, momentum di breakout, condizione di stress) o è un'iperparametrizzazione casuale del backtest? + +**Top-1**: TBD. +**Top-2**: TBD. +**Top-3**: TBD. +**Top-4**: TBD. +**Top-5**: TBD. + +### 3.2 Ratio top-5 / median + +Median DSR popolazione: TBD. Mediana DSR top-5: TBD. Ratio: TBD (gate 1.5x). + +--- + +## 4. Parser failure modes + +**Domanda gate 2**: l'output LLM è strutturalmente affidabile? + +### 4.1 Statistiche aggregate + +- Evaluations totali: TBD +- Parse success: TBD (TBD%) +- Parse failure: TBD (TBD%) + +### 4.2 Tassonomia degli errori + +Per ognuna delle classi sotto, riportare frequenza assoluta e relativa: + +- **No s-expression found in output**: TBD. Causa tipica: l'LLM ha restituito prosa senza fence o senza `(strategy ...)` esplicito. +- **sexp parse error**: TBD. Causa tipica: parentesi sbilanciate, syntax non valida. +- **Unknown verb**: TBD. Causa tipica: LLM ha inventato verbi non in `VERBS`. +- **Validation error (unknown indicator/feature)**: TBD. Causa tipica: LLM ha usato indicatori non presenti in `KNOWN_INDICATORS`. +- **Validation error (wrong arity)**: TBD. Causa tipica: numero argomenti errato per verbi specifici. + +### 4.3 Failure mode più frequente — analisi qualitativa + +Esempio di output LLM che ha causato il failure dominante: TBD. + +Suggerimenti per Phase 2 (es. arricchire il prompt con esempi negativi, validare con DSPy o restrict to JSON instead of S-expression): TBD. + +--- + +## 5. Costi reali vs preventivo + +**Domanda gate 5**: la spesa è prevedibile? + +### 5.1 Breakdown costi LLM + +| Tier | Calls | Input tokens | Output tokens | Cost USD | +|---|---|---|---|---| +| C | TBD | TBD | TBD | TBD | +| Altri | TBD | TBD | TBD | TBD | +| **Totale** | TBD | TBD | TBD | **TBD** | + +### 5.2 Ablation tier (se eseguito) + +Phase 1 lean spike usa solo tier C. Ablation B vs C rinviata a Phase 2 (spec sez. 5.1). + +### 5.3 Confronto con preventivo + +- Preventivo: $500-700 (mid $600). +- Spesa reale: $TBD. +- Deviazione: TBD%. +- Tokens medi per call: TBD input, TBD output. + +### 5.4 Estrapolazione costi Phase 2 + +Phase 2 prevede K=40 (× 2x), 15 generazioni (× 1.5x) e tier mix (~30% B, 10x più caro). Estrapolazione lineare: TBD × 2 × 1.5 × ~3 = $TBD. Confronto con cap Phase 2 ($700-1100): rientrano. + +--- + +## 6. Diversity metrics + +**Domanda gate 4**: la diversità cognitiva sopravvive alla pressione selettiva? + +### 6.1 Entropy fitness per generazione + +(Vedi tabella sez. 2.1 colonna entropy.) + +### 6.2 Cognitive style sopravvissuti + +| Stile | Gen 0 (count) | Gen finale (count) | +|---|---|---| +| physicist | TBD | TBD | +| biologist | TBD | TBD | +| historian | TBD | TBD | +| meteorologist | TBD | TBD | +| ecologist | TBD | TBD | +| engineer | TBD | TBD | + +### 6.3 Signal correlation fra top-5 + +Phase 1 non implementa speciation né novelty bonus, quindi è plausibile vedere alta correlazione fra i top performer. Misura indicativa (Pearson correlation fra signal series dei top-5 sull'OOS): TBD. Se ρ > 0.7, top-5 sono cloni leggeri — implicazione architetturale per Phase 2 (necessità di novelty bonus o speciation). + +--- + +## 7. Threats to validity + +Lista esplicita dei limiti metodologici e dei rischi di sovra-interpretare i risultati: + +1. **In-sample fitting**: tutto il backtest è sullo stesso range usato per generare le ipotesi. Phase 2 introduce walk-forward + hold-out finale per misurare overfitting. +2. **Mock LLM-driven exploration con tier C unico**: nessun confronto contro tier B / S. Possibile underperformance vs Sonnet/Opus che potrebbero generare strategie qualitativamente diverse. +3. **Adversarial layer hand-crafted**: i 4 check (no_trades, degenerate, overtrading, undertrading) sono euristici. Phase 2 introduce 5 prompt LLM-driven dedicati (data snooping, lookahead, regime fragility, crowding, transaction cost erosion). +4. **Fitness function v0**: lineare in DSR + drawdown penalty. Non multi-livello (per-team, anti-collusion). Phase 2 introduce. +5. **No speciation, no novelty bonus**: convergenza prematura plausibile. Documentata nello spec sez. 8.4. +6. **Cerbero/Deribit data quality**: nessuna detection di gap, outlier, exchange downtime. Da affrontare prima di forward-test (Phase 3). +7. **Costi LLM volatili**: pricing OpenRouter per qwen3 può variare. Stima Phase 2 può cambiare significativamente. + +--- + +## 8. Conclusioni e implicazioni per Phase 2 + +**Hard gate sintesi**: TBD su 5 passati. + +**Decisione preliminare**: rimandato al `docs/decisions/2026-05-10-gate-phase1.md` (decision memo). + +**Apprendimenti chiave per Phase 2** (popolare a chiusura): + +- TBD. + +**Riusabilità del codebase Phase 1**: il design modulare (data, backtest, metrics, cerbero, protocol, genome, llm, agents, ga, persistence, orchestrator, dashboard) è riutilizzabile direttamente in Phase 2. Estensioni richieste: speciation in `ga/`, novelty bonus in `ga/fitness.py`, walk-forward integration in `orchestrator/run.py`, Adversarial LLM-driven in `agents/adversarial.py`, Random Forest baseline in nuovo modulo `baseline/`. + +--- + +*Documento da finalizzare a fine Phase 1. Versione 1.0 — template; popolare con i numeri reali da `runs.db` e screenshot della dashboard.*