docs: scaffolding decision memo + technical report Phase 1
Aggiunge i template per gate decision memo (sez. 4.4 spec) e technical report (sez. 4.5 spec). Da popolare con numeri reali a chiusura del run phase1-real-001 (in corso). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -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.*
|
||||
Reference in New Issue
Block a user