Multi_Swarm_Coevolutive/docs/superpowers/specs/2026-05-19-strategy-pythagoras-design.md

strategy_pythagoras — Design

Data: 2026-05-19 Autore design: Adriano Dal Pastro (con Claude/brainstorming) Stato: Design approvato per parti 1-4, in attesa di review utente sulla spec consolidata Audience: implementatori (Claude executor o umano)

0. Riassunto esecutivo

Nuovo workspace member strategy_pythagoras parallelo a strategy_crypto. Replica il pattern coevolutivo GA del monorepo applicato a un dominio diverso: la scoperta di pattern frattali ricorrenti sui mercati crypto secondo il framework Pythagoras-Malanga (Fourier + frattali + geometria Evideon), descritto nei due PDF in src/strategy_pythagoras/Pythagoras/.

Non cambia il genoma del core: gli agenti restano HypothesisAgentGenome e producono Strategy JSON nella stessa DSL S-expression. Cambiano:

• 7 stili cognitivi Pythagoras-themed (in prompts.json)
• 3 nuovi indicatori candle (candle_pattern, pythagorean_ratio, fractal_mirror)
• Fitness con bonus di asset-invariance BTC↔ETH
• Output: strategie JSON freezate + dashboard NiceGUI + report markdown di analisi cross-book

Deliverable di chiusura task: scaffolding completo + 1 GA run short (smoke test) + docs/analysis_first_run.md con sintesi numerica e top winners.

---

1. Architettura

Layout package

src/strategy_pythagoras/
├── pyproject.toml                     # workspace member, dipende da multi-swarm-core
├── README.md
├── tests/
│   └── test_indicators.py             # unit-test per i 3 nuovi indicatori
└── strategy_pythagoras/
    ├── __init__.py
    ├── prompts.json                   # 7 stili Pythagoras-aligned (schema v3.2 di strategy_crypto)
    ├── indicators.py                  # candle_pattern, pythagorean_ratio, fractal_mirror
    ├── backend/
    │   ├── __init__.py
    │   ├── schema.py                  # tabelle paper_trading_*
    │   ├── executor.py                # PaperExecutor (port da strategy_crypto)
    │   ├── portfolio.py               # Portfolio (port da strategy_crypto)
    │   └── persistence.py             # PaperRepository
    ├── frontend/
    │   ├── __init__.py
    │   ├── nicegui_app.py             # /strategy_pythagoras_gui
    │   └── data.py                    # dual-reader: GA db + paper db + invariance metrics
    └── strategies/                    # JSON winners shippati col package
        └── (vuoto al t0)

Workspace registration

In pyproject.toml (root):

[tool.uv.workspace]
members = ["src/multi_swarm_core", "src/strategy_crypto", "src/strategy_pythagoras"]

[tool.uv.sources]
strategy-pythagoras = { workspace = true }

Aggiungere strategy-pythagoras a [project].dependencies per il deployable root.

Riuso

Componente	Source	Note
GA loop, mutation, crossover	multi_swarm_core.ga	invariato
Protocol parser/validator/compiler	multi_swarm_core.protocol	esteso con 3 indicatori (vedi §2)
Backtest engine	multi_swarm_core.backtest	invariato
LLM / OpenRouter / Anthropic clients	multi_swarm_core.llm	invariato
PaperExecutor + Portfolio	strategy_crypto.backend	port (non import), per isolamento DB
NiceGUI dashboard shell	strategy_crypto.frontend	port + adatta tabs

Persistence

state/strategy_pythagoras.db          # GA: genomi, generazioni, fitness history
state/strategy_pythagoras_paper.db    # paper-trading post-deploy
strategy_pythagoras/strategies/       # JSON winners shippati
docs/analysis_first_run.md            # report cross-book
docs/analysis_runs/<run-id>/          # per-run dump

Env vars:

• STRATEGY_PYTHAGORAS_DB_PATH (default state/strategy_pythagoras.db)
• STRATEGY_PYTHAGORAS_PAPER_DB_PATH (default state/strategy_pythagoras_paper.db)
• GA_INVARIANCE_ALPHA (default 0.3)
• GA_INVARIANCE_TOLERANCE_BARS (default 36 = ±3h su 5m TF)

Routing GUI

/strategy_pythagoras_gui (allinea a gui_subpath_routing in memory: ogni asset GUI su subpath, root dominio libera).

Docker (Phase 2, fuori scope di questa spec)

Servizi paralleli a quelli di strategy_crypto:

• strategy-pythagoras-paper (runner)
• strategy-pythagoras-gui (dashboard) Rete Traefik external, bind mount uid 1000 (vedi production_deployment).

---

2. Genoma e DSL

Il genoma non cambia

HypothesisAgentGenome di multi_swarm_core.genome.hypothesis resta identico:

• system_prompt: str
• feature_access: list[str]
• temperature: float
• top_p: float
• model_tier: ModelTier
• lookback_window: int — vincolo 12 ≤ lw ≤ 200
• cognitive_style: str — uno dei 7 nuovi stili
• parent_ids, generation, id — invariati

3 nuovi indicatori (strategy_pythagoras/indicators.py)

Nome	Params (JSON)	Output	Semantica operativa
candle_pattern	[seq_str] es. "UDU", "UUD0U"	1.0 se le ultime k=len(seq_str) candele matchano la sequenza, 0.0 altrimenti	"U" = close>open; "D" = close<open; "0" = abs(close-open)/open < 0.001
pythagorean_ratio	[lookback: int]	float = max(close[-lookback:]) / min(close[-lookback:])	Ratio prezzo, da confrontare con literal vicini a φ=1.618, π=3.1416, √2=1.414, e=2.718
fractal_mirror	[k: int, axis: str] axis ∈ {"h","v"}	float ∈ [-1, +1]	Correlazione di Pearson tra ultime k candele e loro mirror: "h" = mirror tempo (inversione sequenza); "v" = mirror prezzo (1 - close/max)

Vincoli del compiler:

• candle_pattern: len(seq_str) ∈ [3, 12], simboli ∈ {U,D,0}
• pythagorean_ratio: lookback ∈ [12, 200]
• fractal_mirror: k ∈ [3, 12], axis ∈ {"h","v"}

Tutti e 3 vanno aggiunti a KNOWN_INDICATORS in multi_swarm_core.protocol.grammar.

Esempio strategy JSON tipica

{
  "rules": [
    {
      "condition": {
        "op": "and",
        "args": [
          {"op": "eq", "args": [
            {"kind": "indicator", "name": "candle_pattern", "params": ["UDDU"]},
            {"kind": "literal", "value": 1.0}
          ]},
          {"op": "gt", "args": [
            {"kind": "indicator", "name": "pythagorean_ratio", "params": [89]},
            {"kind": "literal", "value": 1.618}
          ]}
        ]
      },
      "action": "entry-long"
    },
    {
      "condition": {
        "op": "or", "args": [
          {"op": "gt", "args": [
            {"kind": "indicator", "name": "pythagorean_ratio", "params": [89]},
            {"kind": "literal", "value": 2.618}
          ]},
          {"op": "crossunder", "args": [
            {"kind": "indicator", "name": "fractal_mirror", "params": [12, "h"]},
            {"kind": "literal", "value": 0.0}
          ]}
        ]
      },
      "action": "exit"
    }
  ]
}

Vincoli protettivi (anti-overfitting)

• lookback_window ≤ 200
• candle_pattern seq length ∈ [3, 12] (range 1+2 del Libro dei Frattali)
• time_in_market monitorato come metric (red flag selectivity_red_flag); non hard-gate al primo run
• Letterali con pythagorean_ratio: max 4 decimali (no 1.6180339)
• Max 4 condizioni in AND per regola (eredita da prompts.json)

---

3. Stili cognitivi (strategy_pythagoras/prompts.json)

Schema

Schema v3.2 identico a strategy_crypto/prompts.json (campi _schema, _changelog, _design_invariants, agent_role, pattern_guidance, instruction, domain_warnings, anti_patterns, output_priorities, styles).

agent_role

Sei un agente di un sistema swarm coevolutivo che cerca pattern frattali ricorrenti sui mercati crypto secondo il framework Pythagoras-Malanga (frattali H-C, trasformata di Fourier, geometria Evideon). Sei parte di una popolazione che esplora collettivamente lo spazio dei pattern: la diversità delle ipotesi è un asset critico. Preferisci esplorare strutture meno ovvie per la tua lente cognitiva. La strategia che produci deve essere riconoscibile come emanata dal tuo stile.

pattern_guidance (specifico Pythagoras)

• Sequenze candle 3-12 lunghezza in alfabeto {U,D,0} via candle_pattern
• Mirror H/V come operatori di proiezione via fractal_mirror
• Ratios di prezzo vicini a φ=1.618, 1/φ=0.618, √2=1.414, π/2=1.571, e/2=1.359 entro tolleranza 0.5%
• Pattern composti: pattern lunghi (6-12) come concatenazione di pattern corti (Pattern 13 = Pattern 3 + Pattern 11, p. 53 del paper)
• Cicli ricorrenti: stesso pattern firato a distanze regolari (Poincaré)

domain_warnings

• Crypto 24/7, no CME gap
• I "numeri sacri" (Solfeggio 396-852 Hz, 137.0359, etc.) sono prior teorici, NON leggi: usali come scale candidate, non come dogma
• Il paper Pythagoras è esplicitamente non-falsificabile (cita "consapevolezza del trader" come jolly per il fallimento): il backtest è l'unico arbitro
• time_in_market > 80% red flag (leveraged B&H camuffato)
• Tolleranza ±3h del paper → su 5m TF = ±36 barre

anti_patterns

• Sequenza candle_pattern con len > 7 simboli vincolati → overfitting
• pythagorean_ratio con tolleranza > 2% sui literal → numerologia spuriosa
• fractal_mirror con k == lookback_window → tautologico
• Letterali con più di 4 decimali
• Più di 4 condizioni in AND
• Crossover tra indicatori dello stesso tipo con lookback vicini → chattering

output_priorities

1. Coerenza con lente cognitiva (es. pythagorean usa ratios, candle_grammarian usa sequenze esplicite)
2. Asset-invariance (segnali che attivano sia su BTC che su ETH entro ±36 barre)
3. Selettività (poche entry forti)
4. Composizionalità (pattern lunghi come somma di corti)
5. Robustezza vs random baseline (3σ richiesto da skeptic_quant)

I 7 stili (styles)

Ogni stile mantiene shape v3.2 (directive 800-950 char ASCII-safe, focus_metrics 4 voci, ultimo periodo = "Archetipo dominante: X.", lookback range esplicito):

cognitive_style	Archetipo / Metafora ancorante	focus_metrics	Lookback consigliato
pythagorean	Armonia di ratios sacri (φ, π, √2)	pythagorean_ratio, candle_pattern, sma_pct, realized_vol	89-144
fractal_geometer	Autosimilarità: pattern di 3 candele si ripetono dilatati a 6, 12	candle_pattern, fractal_mirror, atr_pct, pythagorean_ratio	48-144
fourier_analyst	Somma di seni: frequenze ricorrenti dominanti	sma_pct, realized_vol, candle_pattern, atr	60-200
evideonic_projector	Presente = passato proiettato via mirror H+V e scale	fractal_mirror, pythagorean_ratio, candle_pattern, sma_pct	24-96
candle_grammarian	Lingua di 3 simboli (U,D,0); parole 3-12 lettere	candle_pattern, volume, atr, realized_vol	12-48
recurrence_theorist	Per Poincaré, eventi tornano: cerca pattern di oggi che firarono ieri	candle_pattern, fractal_mirror, pythagorean_ratio, sma_pct	100-200
skeptic_quant	Anticorpo all'unfalsifiability: solo edge 3σ vs random	realized_vol, atr_pct, sma_pct, candle_pattern	60-150

Lo skeptic_quant è importante: la sua directive richiede esplicitamente che la strategia sia testabile e che il fitness sia confrontato contro random baseline.

_design_invariants

Stessa filosofia di v3.2 di strategy_crypto:

• ASCII-safe (no Unicode oltre U+007F nelle directive)
• Ogni directive chiude con Archetipo dominante: <metafora>.
• Ogni directive ha range lookback numerico esplicito
• Prima frase: Il mercato e ...
• Lunghezza 800-950 char

---

4. Fitness, run GA short, deliverable analisi

Fitness con bonus invariance

fitness(genome) = mean(sharpe_BTC, sharpe_ETH) × (1 + α × invariance_score)

invariance_score = corr_signal(entries_BTC, entries_ETH, tolerance_bars=GA_INVARIANCE_TOLERANCE_BARS)
                 ∈ [0, 1]
α = GA_INVARIANCE_ALPHA (default 0.3)

corr_signal = frazione di entries su BTC che hanno una entry corrispondente su ETH entro ±36 barre (=±3h su 5m TF).

Implementazione come callback al GA in multi_swarm_core.ga, registrata da strategy_pythagoras al startup. Il core non sa nulla di Pythagoras: riceve solo la callback.

GA run short (smoke test)

Parametro	Valore	Note
population_size	20	minimo per 7 stili (~3 per stile)
generations	5	smoke test, non training
elite_fraction	0.2	top-4 sopravvivono
mutation_rate	0.3	invariato vs strategy_crypto
crossover_rate	0.5	invariato
model_tier distribuzione	70% C (qwen-2.5-72b), 30% B (sonnet)	rispetta model_qwen_dependency
dataset	BTC 5m + ETH 5m da strategy_crypto/series/	riusa serie esistenti
train_window	2024-07 → 2024-12	copre le date Pythagoras (lug-ago 2024)
test_window	2025-01 (1 mese)	hold-out per validare invariance
name	pythagoras-smoke-001	run id

Lo smoke test verifica:

1. Workspace member installato in venv (uv sync + uv run python -c "import strategy_pythagoras")
2. I 3 nuovi indicatori registrati nel grammar e compilabili
3. prompts.json caricato, 7 stili producono genomi distinti (no collisioni di id)
4. Bonus invariance impatta fitness (verifica via log)
5. JSON winners atterrano in strategy_pythagoras/strategies/
6. Dashboard NiceGUI si avvia e legge i due DB

Deliverable analisi cross-book

docs/analysis_first_run.md con:

1. Sintesi numerica dei riassunti — riferimenti a src/strategy_pythagoras/Pythagoras/Pythagoras_Trading_Prediction.summary.md e Libro_frattali.summary.md
2. Top-5 winners — id, cognitive_style, fitness, sharpe_BTC, sharpe_ETH, invariance_score
3. Pattern frattali emersi — dump dei candle_pattern seq usate, conteggio per stile, % sovrapposizione con spazio teorico dei 57 pattern del Libro
4. Ratios di prezzo emersi — distribuzione literal usati con pythagorean_ratio, distanza dai numeri universali (φ/π/√2/Solfeggio)
5. Cross-asset invariance osservata — istogramma di corr_signal per top genomi
6. Conclusione onesta — confronto vs random baseline, quanti winners superano sharpe>1.0 su test + invariance>0.3, cosa il framework Pythagoras predice e cosa NON regge al backtest

Niente "consapevolezza" come jolly. Solo numeri.

Dashboard NiceGUI

/strategy_pythagoras_gui:

• Tab Genomes — winners con stile/sharpe/invariance, click per drill su rules
• Tab Patterns — heatmap delle sequenze candle_pattern emerse, frequenza per stile
• Tab Ratios — istogramma literal vicini a costanti universali, bins centrati su φ, π, √2, ecc.
• Tab Invariance — scatter sharpe_BTC vs sharpe_ETH per ogni winner

---

5. Out-of-scope (esplicito)

• Asset oltre BTC/ETH (Oro/Argento del paper): non in primo run. Estensione futura.
• Range candele oltre 12: range 3-5 del Libro (12-56 candele). Estensione futura quando lo smoke test conferma stabilità.
• Live trading reale: solo paper-trading via stesso pattern di strategy_crypto.
• OCR/Vision sulle figure del Libro dei Frattali: esplicitamente ESCLUSO da request utente ("senza passare alle immagini").
• Modifica del genoma del core: nessuna modifica a HypothesisAgentGenome. Solo extension del grammar (3 indicatori).
• Riferimenti pseudoscientifici operativizzati come legge: i numeri sacri/Solfeggio sono prior teorici per literal candidati, non vincoli rigidi.

---

6. Criteri di accettazione

• uv sync riesce dalla root con strategy_pythagoras come member
• uv run python -c "from strategy_pythagoras.indicators import candle_pattern, pythagorean_ratio, fractal_mirror" non solleva
• pytest src/strategy_pythagoras/tests/ verde (almeno unit-test per i 3 indicatori)
• GA short run pythagoras-smoke-001 completa 5 generazioni senza errori
• Almeno 1 winner con fitness > 0 e cognitive_style ∈ {7 stili Pythagoras}
• Dashboard avvia su http://localhost:PORT/strategy_pythagoras_gui e mostra winners
• docs/analysis_first_run.md esiste e contiene tutte le sezioni elencate in §4

---

7. Riferimenti

• Pythagoras Trading Prediction — riassunto
• Libro dei Frattali — riassunto
• Memory: monorepo_uv_workspace, gui_subpath_routing, ownership_per_modulo, production_deployment, model_qwen_dependency, selectivity_red_flag
• Template: src/strategy_crypto/ (paper-trading + GUI), src/strategy_crypto/strategy_crypto/prompts.json (schema v3.2)
• Core: src/multi_swarm_core/multi_swarm_core/genome/hypothesis.py, multi_swarm_core/protocol/grammar.py