From 96bbd716ec4a6338c60e65f01c21e02b3f0a3bd4 Mon Sep 17 00:00:00 2001 From: Adriano Dal Pastro Date: Fri, 15 May 2026 18:03:31 +0000 Subject: [PATCH] docs(readme): allinea a monorepo unificato (workspace uv + strategy_crypto subpath) - Sezione "Layout monorepo (uv workspace)": ridisegna la struttura per chiarire i due workspace member (multi-swarm-core + strategy-crypto), DB separati, pattern per N strategie future. - Comandi aggiornati: paper runner ora importa da strategy_crypto.backend, dashboard via 'python -m strategy_crypto.frontend.nicegui_app'. - Backtest cmd punta al nuovo path strategie src/strategy_crypto/strategy_crypto/strategies/. - Variabili .env: GA_DB_PATH + STRATEGY_CRYPTO_DB_PATH + DASHBOARD_ROOT_PATH. Mantenuto nota backcompat su DB_PATH legacy. - Dashboard: nuova pagina /paper + URL prod /strategy_crypto_gui/. - Deploy: servizi rinominati strategy-crypto-paper / strategy-crypto-gui, bind strategies dal package, image rinominata multi-swarm-coevolutive:dev. - Rimossi link a doc cancellati (poc_trading_swarm.md, superpowers/, phase1-technical-report). - Doc rimanenti riposizionati sotto src/multi_swarm_core/docs/. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 211 ++++++++++++++++++++---------------------------------- 1 file changed, 77 insertions(+), 134 deletions(-) diff --git a/README.md b/README.md index 3622211..18bcc45 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 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. Il tutto è ispirato alla filosofia di Renaissance Technologies adattata a un contesto retail single-author con LLM agents. +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 @@ -10,99 +10,62 @@ Gitea Tielogic (privato, accesso SSH): 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` live 24/7 in Docker (`https://swarm.tielogic.xyz` per la dashboard) con due strategie freezate: +**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: -- `strategies/btc_fb63e851.json` — BTC-PERPETUAL, true alpha hour-gated (RSI estremi + ATR vs SMA + filtro orario 9-17), Sharpe OOS +0,26 su 7,33 anni di storia. -- `strategies/eth_facd6af85d5d.json` — ETH-PERPETUAL, trend-following long-bias + vol regime, Sharpe OOS +0,19 su 6,75 anni. +- `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 tutte chiuse (30 run GA, $3.74 cumulato LLM, cap originale $700 → margine 99%+). Vedi il documento di sintesi consolidato per il dettaglio: +Phase 1 → 2.7 chiuse (30 run GA, $3.74 cumulato LLM). -- [**Stato progetto e roadmap (14 maggio 2026)**](docs/reports/2026-05-14-stato-progetto-e-roadmap.md) — riepilogo di tutte le fasi, decisioni, caveat aperti, roadmap. +- [**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/). -Documenti chiave per fase: - -- [Decisione strategica](docs/superpowers/specs/2026-05-09-decisione-strategica-design.md) — perché Phase 1 prima, Phase 2 poi, Phase 3 forward-test. -- [Decision memo gate Phase 1](docs/decisions/2026-05-10-gate-phase1.md), [Technical report Phase 1](docs/reports/2026-05-10-phase1-technical-report.md), [Decision memo Phase 1.5 nemotron](docs/decisions/2026-05-11-phase1-5-nemotron-run.md). -- [Piano Phase 2.5 prompt-mutator](docs/superpowers/plans/2026-05-11-mutate-prompt-llm-phase-2-5.md), [Piano feature temporali](docs/superpowers/plans/2026-05-11-temporal-features.md). - -Documenti di contesto pre-implementazione: `00_documento_zero.md` (framework concettuale Renaissance → swarm), `coevolutive_swarm_system.md` (Filone A, sistema completo), `poc_trading_swarm.md` (Filone B, PoC trading). - -## 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 (Phase 2.6) -├── 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) -│ └── diversity.py Entropy/diversity metrics popolazione (Phase 2.5) -├── 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 (incl. hour/dow/is_weekend) -│ ├── 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 scalari (temp, lookback, features, style) -│ ├── mutation_prompt_llm.py 5° operatore: riscrittura system_prompt via LLM tier B -│ └── crossover.py Uniform crossover -├── llm/ -│ ├── client.py Unified LLMClient via OpenRouter (tier S/A/B/C/D) -│ └── cost_tracker.py Pricing per tier, breakdown + call_kind tracking -├── agents/ -│ ├── hypothesis.py LLM call + JSON extract + retry-with-feedback -│ ├── falsification.py Compile → backtest → DSR -│ ├── adversarial.py Red-team heuristics (5 check HIGH parametrici via CLI) -│ └── market_summary.py Stats di mercato per il prompt -├── ga/ -│ ├── selection.py Tournament + elitism -│ ├── fitness.py v1 continua + v2 soft-kill + combined IS/OOS opt-in -│ ├── 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 GA + 5 tabelle paper_trading_* -│ └── repository.py CRUD per runs/genomes/evals/cost/findings/gen_summary -├── paper_trading/ Phase 3 -│ ├── portfolio.py Multi-asset portfolio con sleeve uguali per asset -│ ├── executor.py PaperExecutor: carica strategia JSON, valuta ultimo bar -│ └── persistence.py PaperRepository (paper_trading_runs/ticks/equity/trades/positions) -├── orchestrator/ -│ └── run.py End-to-end pipeline GA + persistence -└── dashboard/ - ├── nicegui_app.py NiceGUI dashboard (overview / convergence / genomes) - └── data.py Lettura runs.db per le pagine -``` - -Stack: Python 3.13, uv, pytest+pytest-mock+responses, openai SDK (verso OpenRouter), requests+tenacity, pandas+numpy+scipy, sqlmodel+sqlite, nicegui+plotly, yfinance (test cross-asset non-crypto). - -CLI knobs accumulati (Phase 2.5 → 2.7): - -- `--prompt-mutation-weight FLOAT` (peso del 5° operatore, sweet spot 0.20-0.30) -- `--fees-eat-alpha-threshold FLOAT` (default 0.5, suggerito 0.7) -- `--flat-too-long-threshold FLOAT` (default 0.95) -- `--undertrading-threshold INT` (default 20) -- `--fitness-v2` + `--fitness-soft-penalty FLOAT` -- `--fitness-combined-alpha FLOAT` (multi-obiettivo IS/OOS) -- `--min-trades-threshold INT` (filtro OOS in WFA) +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 -cp .env.example .env # compilare CERBERO_*_TOKEN e OPENROUTER_API_KEY -uv run pytest # ~180 test attesi (unit + integration) +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 @@ -116,36 +79,27 @@ CERBERO_BOT_TAG=swarm-poc-phase1 # LLM provider (unico endpoint via OpenRouter) OPENROUTER_API_KEY= -OPENROUTER_BASE_URL=https://openrouter.ai/api/v1 -# Modelli per tier (default Phase 2.5+: qwen-2.5-72b per tier C, vedi .env.example per gli altri) -LLM_MODEL_TIER_C=qwen/qwen-2.5-72b-instruct +# 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 (vedi sezione Deploy) +# Deploy Docker DOMAIN_NAME=tielogic.xyz SWARM_DASHBOARD_PORT=8080 +DASHBOARD_ROOT_PATH=/strategy_crypto_gui # subpath traefik per la dashboard ``` -### Cerbero MCP - -Tutti i fetch OHLCV passano da Cerbero MCP (sostituisce ccxt). In sviluppo locale: - -```bash -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 produzione/integrazione: VPS `https://cerbero-mcp.tielogic.xyz` (richiede bearer) — o internal docker `http://cerbero-mcp:9000` se si gira nella stessa rete Traefik. +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 tests/unit -v # solo unit -uv run pytest tests/integration -v # solo integration (richiedono Cerbero + OpenRouter) -uv run ruff check src/ tests/ scripts/ +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) @@ -160,67 +114,56 @@ uv run python scripts/run_phase1.py \ --population-size 20 --n-generations 10 \ --prompt-mutation-weight 0.30 --fitness-v2 -# Backtest standalone di una strategia JSON su range esteso +# Backtest standalone di una strategia JSON uv run python scripts/backtest_strategy.py \ - --strategy strategies/btc_fb63e851.json \ + --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 -DB_PATH=./runs.db uv run python -m multi_swarm.dashboard.nicegui_app +uv run python -m strategy_crypto.frontend.nicegui_app +# → http://localhost:8080 (env SWARM_DASHBOARD_PORT) ``` ## Dashboard -NiceGUI dashboard (dark/neon palette) su `http://localhost:8080` (override con env `SWARM_DASHBOARD_PORT`): +NiceGUI dashboard (dark palette) — **dual-DB reader** (GA + paper): -- **Overview** (`/`): lista runs, status, costo, metriche aggregate evaluations (parse success %, top fitness, median). -- **GA Convergence** (`/convergence`): fitness median/max/p90 per generazione, entropy con hline a soglia gate (0.5). -- **Genomes** (`/genomes`): top-K ordinati per fitness, click su riga per ispezione system_prompt + raw_text JSON strategy. +- **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 gira dentro Docker dietro Traefik su `https://swarm.${DOMAIN_NAME}` — vedi sezione Deploy. +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 che condividono la stessa immagine `multi-swarm:dev`: +`docker-compose.yml` definisce due servizi su immagine `multi-swarm-coevolutive:dev`: -- **`multi-swarm-paper`** — runner `scripts/run_paper_trading.py` long-running (`restart: unless-stopped`). -- **`multi-swarm-dashboard`** — NiceGUI esposta via Traefik su `https://swarm.${DOMAIN_NAME}`. +- **`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/`. -Entrambi joinano la rete external `traefik` per parlare direttamente con `cerbero-mcp:9000` senza giro pubblico+TLS. Persistenza via bind mount: - -- `./data/`, `./series/` — cache OHLCV (parquet) -- `./state/` — `runs.db` (+ WAL/SHM) -- `./strategies/` — `btc_*.json` / `eth_*.json` (read-only nel container) - -Bring-up: +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 multi-swarm-paper # segui i tick -docker compose ps # stato +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-trading via env (`PAPER_RUN_NAME`, `PAPER_INITIAL_CAPITAL`, `PAPER_POLL_SECONDS`, ecc.) — vedi `.env.example`. -- `SWARM_DASHBOARD_PORT` controlla la porta interna del container (Traefik fa il TLS davanti). - -## Costi - -Costo cumulato LLM progetto a oggi: **≈ $3.74** su 30 run GA (Phase 1 → 2.7). Cap originale Phase 1: $700 → margine residuo abbondante. - -- Tier C (qwen-2.5-72b via OpenRouter): ~$0.40/1M token. -- Run base K=20 × 10gen ≈ $0.07. Con `--prompt-mutation-weight 0.30` overhead mutator 3-9%. -- **Phase 3 paper-trading**: $0 incrementali LLM (strategie fisse), solo costi Cerbero (servizio esistente). +- 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`. Single-author retail R&D, nessun feature branch attivo. Ablation paralleli si gestiscono via CLI knobs sullo stesso branch. +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).