Multi_Swarm_Coevolutive

Proof-of-concept di sistema co-evolutivo multi-agente per trading quantitativo. Un genetic algorithm fa evolvere una popolazione di agenti LLM (Hypothesis swarm) che generano strategie di trading espresse in JSON strutturato; un layer Falsification deterministico le backtesta su dati storici BTC-PERPETUAL via Cerbero MCP; un layer Adversarial euristico le sottopone a red-team checks; la fitness combina Deflated Sharpe Ratio (Bailey & López 2014), Sharpe normalizzato e penalizzazione di drawdown. Il tutto è ispirato alla filosofia di Renaissance Technologies adattata a un contesto retail single-author con LLM agents.

Stato del progetto

Phase 1 (lean spike) completata il 10 maggio 2026 con tutti i 5 hard gate passati (loop convergence, parse success 100%, top-5 ratio 1116x, entropy 0.914, costo $0.069 vs cap $700). Decisione strategica: GO Phase 2 con tre aggiustamenti (Adversarial soglie più strette, speciation, walk-forward 70/30).

Documenti chiave:

• Decisione strategica — perché Phase 1 prima, Phase 2 poi, Phase 3 forward-test.
• Piano implementativo Phase 1 — 38 task TDD-driven.
• Decision memo gate Phase 1 — valutazione formale dei 5 hard gate.
• Technical report Phase 1 — risultati, ispezione top genomi, threats to validity.

Documenti di contesto pre-implementazione:

• 00_documento_zero.md — framework concettuale (Renaissance → swarm co-evolutivo LLM).
• coevolutive_swarm_system.md — design Filone A (sistema completo, 12-18 mesi).
• poc_trading_swarm.md — design Filone B (PoC trading, fonte di Phase 1).

Architettura

src/multi_swarm/
├── config.py                Settings Pydantic (.env)
├── data/
│   ├── cerbero_ohlcv.py     OHLCV loader via Cerbero MCP + cache parquet
│   └── splits.py            Walk-forward expanding splits
├── backtest/
│   ├── orders.py            Side/Order/Position/Trade
│   └── engine.py            Event-driven backtest, 1-bar exec delay
├── metrics/
│   ├── basic.py             Sharpe, max drawdown, total return
│   └── dsr.py               Deflated Sharpe Ratio (Bailey & López 2014)
├── cerbero/
│   ├── client.py            HTTP client (bearer + bot-tag + retry tenacity)
│   └── tools.py             Wrapper tool MCP (sma/rsi/atr/macd/realized_vol/funding)
├── protocol/
│   ├── grammar.py           Vocabolario operatori, indicatori, feature
│   ├── parser.py            json.loads → AST dataclass tipizzato
│   ├── validator.py         Arity checks, no-nesting indicators, whitelist
│   └── compiler.py          AST → Callable[[df], Series[Side]]
├── genome/
│   ├── hypothesis.py        HypothesisAgentGenome (id deterministico)
│   ├── mutation.py          4 operatori (temp, lookback, features, style)
│   └── crossover.py         Uniform crossover
├── llm/
│   ├── client.py            Unified LLMClient via OpenRouter (tier S/A/B/C/D)
│   └── cost_tracker.py      Pricing per tier, breakdown
├── agents/
│   ├── hypothesis.py        LLM call + JSON extract + retry-with-feedback
│   ├── falsification.py     Compile → backtest → DSR
│   ├── adversarial.py       Red-team heuristics (no_trades/degenerate/over/under)
│   └── market_summary.py    Stats di mercato per il prompt
├── ga/
│   ├── selection.py         Tournament + elitism
│   ├── fitness.py           v1 continua: dsr + tanh(sharpe) × penalty(dd)
│   ├── loop.py              next_generation step
│   ├── summary.py           median/max/p90/entropy per gen
│   └── initial.py           Popolazione iniziale (6 cognitive style)
├── persistence/
│   ├── schema.py            SQLite DDL: 6 tabelle + 3 indici
│   └── repository.py        CRUD per runs/genomes/evals/cost/findings/gen_summary
├── orchestrator/
│   └── run.py               End-to-end pipeline + persistence
└── dashboard/
    ├── streamlit_app.py     Hub multipage
    ├── data.py              Lettura runs.db per le pagine
    ├── aquarium.py          Helper canvas HTML5 (fish data + JS template)
    └── pages/
        ├── 01_overview.py       Run + metriche aggregate
        ├── 02_ga_convergence.py Fitness convergence + entropy plot
        ├── 03_genomes.py        Top-10 + ispezione system_prompt
        └── 04_aquarium.py       Acquario 2D con click → info + lineage

Stack: Python 3.13, uv, pytest+pytest-mock+responses, openai SDK (verso OpenRouter), requests+tenacity, pandas+numpy+scipy, sqlmodel+sqlite, streamlit+plotly.

Setup

uv sync
cp .env.example .env  # compilare CERBERO_*_TOKEN e OPENROUTER_API_KEY
uv run pytest         # verifica che tutto installi (141 test attesi)

Variabili .env richieste

# Cerbero MCP (locale o VPS https://cerbero-mcp.tielogic.xyz)
CERBERO_BASE_URL=http://localhost:9001
CERBERO_TESTNET_TOKEN=<testnet bearer>
CERBERO_MAINNET_TOKEN=<mainnet bearer>   # serve per dati storici reali
CERBERO_BOT_TAG=swarm-poc-phase1

# LLM provider (unico endpoint via OpenRouter)
OPENROUTER_API_KEY=<sk-or-v1-...>
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

# Modelli per tier (override dei default se serve)
LLM_MODEL_TIER_S=anthropic/claude-opus-4-7
LLM_MODEL_TIER_A=anthropic/claude-sonnet-4-6
LLM_MODEL_TIER_B=anthropic/claude-sonnet-4-6
LLM_MODEL_TIER_C=qwen/qwen-2.5-72b-instruct
LLM_MODEL_TIER_D=meta-llama/llama-3.3-70b-instruct

Cerbero MCP

Phase 1 fetcha OHLCV via Cerbero MCP (sostituisce ccxt). Avviare Cerbero locale prima di un run reale:

cd /home/adriano/Documenti/Git_XYZ/CerberoSuite/Cerbero_mcp
uv sync
uv run cerbero-mcp   # ascolta su porta da .env (default 9001 se 9000 è occupato)

In alternativa usare il VPS esistente https://cerbero-mcp.tielogic.xyz (richiede bearer).

Comandi principali

# Quality gates
uv run pytest                       # tutti i test (141 PASSED attesi)
uv run pytest tests/unit -v         # solo unit
uv run pytest tests/integration -v  # solo integration
uv run ruff check src/ tests/ scripts/
uv run mypy src/ scripts/

# Smoke run (MockLLM + OHLCV sintetico, no API calls)
uv run python scripts/smoke_run.py

# Run reale Phase 1 (Cerbero + OpenRouter, ~$0.07 per run K=20 10gen)
uv run python scripts/run_phase1.py \
  --name phase1-run-XXX \
  --exchange deribit --symbol BTC-PERPETUAL --timeframe 1h \
  --start 2024-01-01T00:00:00+00:00 \
  --end 2026-01-01T00:00:00+00:00 \
  --population-size 20 --n-generations 10

# Dashboard
DB_PATH=./runs.db uv run streamlit run src/multi_swarm/dashboard/streamlit_app.py

Dashboard

Streamlit multipage su http://localhost:8501 (override con --server.port):

• Overview: lista runs, status, costo, metriche aggregate evaluations (parse success %, top fitness, median).
• GA Convergence: fitness median/max/p90 per generazione, entropy con hline a soglia gate (0.5).
• Genomes: top-10 ordinati per fitness, click su row per ispezione system_prompt + raw_text JSON strategy.
• Aquarium: visualizzazione 2D canvas HTML5 con un pesce per agente; dimensione ∝ fitness, colore per cognitive_style, halo sui top-3, click su pesce → panel info completo + lineage BFS (parents → grandparents → ...).

Costi tipici Phase 1

Tier C (qwen-2.5-72b via OpenRouter): ~$0.40/1M token. Run K=20 × 10gen ≈ $0.07. Phase 1 totale (5 run incluse iterazioni bug-fix): $0.19.

Per Phase 2 con tier mix B/C (Sonnet 4.6 = $3/$15 input/output) stima: $3-15 per ablation completa.

Sviluppo

Conventional commits con prefix feat: fix: chore: docs: refactor: test:. Body italiano. Footer Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> su ogni commit collaborativo.

Branch attuale: main. Nessun feature branch in Phase 1 (single author, lean spike). Phase 2 valuterà feature branch per ablation paralleli.