# 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 (default BTC-PERPETUAL Deribit) 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, con opzioni v2 soft-kill e combined IS/OOS per Walk-Forward Validation. ## Repository Gitea Tielogic (privato, accesso SSH): ```bash git clone ssh://git@git.tielogic.xyz:222/Adriano/Multi_Swarm_Coevolutive.git ``` ## Layout monorepo (uv workspace) Il repo è un **workspace uv** con due member packages indipendenti: ``` multi_swarm_coevolutive/ repo root (workspace coordinator) ├── pyproject.toml workspace + dev deps + ruff/mypy/pytest ├── docker-compose.yml strategy-crypto-paper + strategy-crypto-gui ├── Dockerfile immagine multi-swarm-coevolutive:dev ├── uv.lock lock unico del workspace ├── data/, series/, state/ cache OHLCV + DB (runtime, gitignored) ├── scripts/ CLI entrypoints (run_phase1, run_paper_trading, ...) └── src/ ├── multi_swarm_core/ WORKSPACE MEMBER (wheel: multi-swarm-core) │ ├── pyproject.toml deps: pandas, numpy, openai, pydantic, ... │ ├── multi_swarm_core/ GA + genome + protocol + backtest + cerbero + │ │ data + llm + agents + ga + orchestrator + │ │ metrics + persistence + config │ ├── tests/ unit + integration (182 test) │ └── docs/ design/ + decisions/ + reports/ │ └── strategy_crypto/ WORKSPACE MEMBER (wheel: strategy-crypto) ├── pyproject.toml deps: multi-swarm-core (workspace) + nicegui + plotly ├── README.md overview strategia + pattern per nuove strategie ├── strategy_crypto/ │ ├── backend/ paper-trading (executor, portfolio, persistence, schema) │ ├── frontend/ NiceGUI dashboard dual-DB │ └── strategies/ JSON freezate (btc_*.json, eth_*.json) └── tests/ smoke regression (import + json + schema) ``` **DB separati per dominio:** `state/runs.db` (GA core universale) + `state/strategy_crypto.db` (paper della strategia crypto). Pattern scala a N strategie senza naming collision. **Pattern N strategie future:** aggiungere `src/strategy_/` con lo stesso scheletro (`backend/`, `frontend/`, `strategies/`, `tests/`), DB dedicato `state/strategy_.db`, servizi Docker `strategy--paper` + `strategy--gui`, GUI su `/strategy__gui`. ## Stato del progetto **Phase 3 (paper-trading forward-test) in corso** dal 13 maggio 2026 su VPS. Runner `scripts/run_paper_trading.py` long-running in Docker, dashboard NiceGUI su `https://swarm.tielogic.xyz/strategy_crypto_gui/`. Due strategie freezate: - `strategy_crypto/strategies/btc_fb63e851.json` — BTC-PERPETUAL, RSI estremi + ATR vs SMA + filtro orario 9-17 (Sharpe OOS +0,26 su 7,33 anni). - `strategy_crypto/strategies/eth_facd6af85d5d.json` — ETH-PERPETUAL, regime-based (Sharpe OOS +0,19 su 6,75 anni). Phase 1 → 2.7 chiuse (30 run GA, $3.74 cumulato LLM). - [**Stato progetto e roadmap (14 maggio 2026)**](src/multi_swarm_core/docs/reports/2026-05-14-stato-progetto-e-roadmap.md) — riepilogo fasi, decisioni, caveat, roadmap. - Decision log: [`src/multi_swarm_core/docs/decisions/`](src/multi_swarm_core/docs/decisions/) (gate Phase 1, scelta nemotron). - Design docs concettuali: [`src/multi_swarm_core/docs/design/`](src/multi_swarm_core/docs/design/). Stack: Python 3.13, uv workspace, hatchling, pytest+pytest-mock+responses, openai SDK (verso OpenRouter), requests+tenacity, pandas+numpy+scipy, sqlmodel+sqlite, nicegui+plotly, yfinance. ## Setup ```bash uv sync # installa entrambi i workspace member come editable cp .env.example .env # compila CERBERO_*_TOKEN e OPENROUTER_API_KEY uv run pytest # 186 test attesi (182 core + 4 smoke strategy_crypto) ``` ### Variabili .env richieste ```bash # Cerbero MCP (locale o VPS https://cerbero-mcp.tielogic.xyz) CERBERO_BASE_URL=http://localhost:9001 CERBERO_TESTNET_TOKEN= CERBERO_MAINNET_TOKEN= # serve per dati storici reali CERBERO_BOT_TAG=swarm-poc-phase1 # LLM provider (unico endpoint via OpenRouter) OPENROUTER_API_KEY= # DB paths (split per dominio: core GA vs paper della strategia) GA_DB_PATH=./state/runs.db STRATEGY_CRYPTO_DB_PATH=./state/strategy_crypto.db # Deploy Docker DOMAIN_NAME=tielogic.xyz SWARM_DASHBOARD_PORT=8080 DASHBOARD_ROOT_PATH=/strategy_crypto_gui # subpath traefik per la dashboard ``` Backcompat: `DB_PATH` legacy continua a funzionare come alias di `GA_DB_PATH`. ## Comandi principali ```bash # Quality gates uv run pytest # tutti i test uv run pytest src/multi_swarm_core/tests/unit -v # solo unit core uv run pytest src/strategy_crypto/tests/ -v # smoke strategy_crypto uv run ruff check src/ 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/2 (Cerbero + OpenRouter, ~$0.07 per run K=20 10gen) uv run python scripts/run_phase1.py \ --name 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 \ --prompt-mutation-weight 0.30 --fitness-v2 # Backtest standalone di una strategia JSON uv run python scripts/backtest_strategy.py \ --strategy src/strategy_crypto/strategy_crypto/strategies/btc_fb63e851.json \ --start 2018-09-01 --end 2026-01-01 # Paper-trading forward-test (Phase 3) uv run python scripts/run_paper_trading.py \ --name phase3-papertrade-XXX \ --initial-capital 1000 --poll-seconds 300 # Default --strategies-dir: importlib.resources del package strategy_crypto # Dashboard NiceGUI locale uv run python -m strategy_crypto.frontend.nicegui_app # → http://localhost:8080 (env SWARM_DASHBOARD_PORT) ``` ## Dashboard NiceGUI dashboard (dark palette) — **dual-DB reader** (GA + paper): - **Overview** (`/`): lista runs GA, costo cumulato, metriche aggregate evaluations. - **GA Convergence** (`/convergence`): fitness median/max/p90 per generazione + entropy. - **Genomes** (`/genomes`): top-K ordinati per fitness, ispezione system_prompt + JSON strategy. - **Paper** (`/paper`): forward-test live con equity curve, posizioni aperte, trade list, tick log. In produzione su `https://swarm.tielogic.xyz/strategy_crypto_gui/` (subpath gestito via `DASHBOARD_ROOT_PATH` + Traefik PathPrefix). La root del dominio resta libera per future GUI di altre strategie. ## Deploy `docker-compose.yml` definisce due servizi su immagine `multi-swarm-coevolutive:dev`: - **`strategy-crypto-paper`** — runner `scripts/run_paper_trading.py` long-running. - **`strategy-crypto-gui`** — NiceGUI dashboard dietro Traefik su `https://swarm.${DOMAIN_NAME}/strategy_crypto_gui/`. Persistenza via bind mount: `./data/`, `./series/`, `./state/`. Le strategie JSON sono bind-mounted in read-only dal package: `./src/strategy_crypto/strategy_crypto/strategies/`. ```bash docker compose up -d --build docker compose logs -f strategy-crypto-paper docker compose ps ``` Note operative: - Le bind-mount dir devono essere `chown 1000:1000` (uid utente `app` nel container). - Override del command paper via env (`PAPER_RUN_NAME`, `PAPER_INITIAL_CAPITAL`, ecc.). - `SWARM_DASHBOARD_PORT` controlla la porta interna del container (Traefik fa il TLS). ## Sviluppo Conventional commits con prefix `feat:` `fix:` `chore:` `docs:` `refactor:` `test:`. Body italiano. Footer `Co-Authored-By: Claude Opus 4.7 (1M context) ` su ogni commit collaborativo. Branch attuale: `main`. Workspace single-repo, monorepo unificato dal 15 maggio 2026 (split temporaneo monorepo→figlio invertito, vedi tag `v0.1.0-pre-split` come bookmark).