Adriano/Multi_Swarm_Coevolutive
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(readme): allinea a stato finale post-refactor sessione 2026-05-15

Browse Source 
Aggiornato per riflettere i 12 commit di refactor della sessione:

  - Layout: 3 servizi Docker (strategy-crypto-paper + strategy-crypto-gui
    + multi-swarm-core-gui), GUI split (core GA / strategy paper)
  - Test: 238 attesi (era 186)
  - Architettura prompt: SYSTEM compositor v3.2 documentato (9 sezioni
    iniettate da scaffold core + contenuto strategy via prompts.json)
  - Grammar: 8 indicatori (5 base + 3 _pct: atr_pct, sma_pct, macd_pct)
  - Input MarketSummary: 14 metriche (5 base + 4 regime + 5 geometria)
  - 7 stili cognitive in prompts.json (era 6, +military_strategist e
    psychologist), con focus_metrics + lookback consigliato + archetipo
  - Deploy: 2 URL distinti (/multi_swarm_core_gui + /strategy_crypto_gui),
    Traefik replacepathregex (NON stripprefix per evitare doppio root_path)
  - Note operative: chown 1000:1000 anche per strategies/ post git mv
  - 3 regression guard test ASCII/archetype/lookback documentati

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Adriano Dal Pastro
2026-05-15 22:05:06 +00:00
parent 6526c6e6e3
commit fa11cca2bc
1 changed files with 84 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+84 -31
View File
@@ -12,23 +12,23 @@ git clone ssh://git@git.tielogic.xyz:222/Adriano/Multi_Swarm_Coevolutive.git
## Layout monorepo (uv workspace) ## Layout monorepo (uv workspace)
Il repo è un **workspace uv** con due member packages indipendenti: Il repo è un **workspace uv** con due member packages indipendenti, principio "**core = framework, strategy = contenuto**":
``` ```
multi_swarm_coevolutive/ repo root (workspace coordinator) multi_swarm_coevolutive/ repo root (workspace coordinator)
├── pyproject.toml workspace + dev deps + ruff/mypy/pytest ├── pyproject.toml workspace + dev deps + ruff/mypy/pytest
├── docker-compose.yml strategy-crypto-paper + strategy-crypto-gui ├── docker-compose.yml 3 servizi su immagine condivisa
├── Dockerfile immagine multi-swarm-coevolutive:dev ├── Dockerfile immagine multi-swarm-coevolutive:dev
├── uv.lock lock unico del workspace ├── uv.lock lock unico del workspace
├── data/, series/, state/ cache OHLCV + DB (runtime, gitignored) ├── data/, series/, state/ cache OHLCV + DB (runtime, gitignored)
├── scripts/ CLI entrypoints (run_phase1, run_paper_trading, ...) ├── scripts/ CLI entrypoints (run_phase1, run_paper_trading, ...)
└── src/ └── src/
├── multi_swarm_core/ WORKSPACE MEMBER (wheel: multi-swarm-core) ├── multi_swarm_core/ WORKSPACE MEMBER (wheel: multi-swarm-core)
│ ├── pyproject.toml deps: pandas, numpy, openai, pydantic, ... │ ├── pyproject.toml core deps (pandas, numpy, openai, pydantic, nicegui, ...)
│ ├── multi_swarm_core/ GA + genome + protocol + backtest + cerbero + │ ├── multi_swarm_core/ GA + genome + protocol + backtest + cerbero +
│ │ data + llm + agents + ga + orchestrator + │ │ data + llm + agents + ga + orchestrator +
│ │ metrics + persistence + config │ │ metrics + persistence + config + dashboard (GA-only)
│ ├── tests/ unit + integration (182 test) │ ├── tests/ unit + integration
│ └── docs/ design/ + decisions/ + reports/ │ └── docs/ design/ + decisions/ + reports/
│ │
└── strategy_crypto/ WORKSPACE MEMBER (wheel: strategy-crypto) └── strategy_crypto/ WORKSPACE MEMBER (wheel: strategy-crypto)
@@ -36,27 +36,73 @@ multi_swarm_coevolutive/ repo root (workspace coordinator)
├── README.md overview strategia + pattern per nuove strategie ├── README.md overview strategia + pattern per nuove strategie
├── strategy_crypto/ ├── strategy_crypto/
│ ├── backend/ paper-trading (executor, portfolio, persistence, schema) │ ├── backend/ paper-trading (executor, portfolio, persistence, schema)
│ ├── frontend/ NiceGUI dashboard dual-DB │ ├── frontend/ NiceGUI paper-only dashboard
│ └── strategies/ JSON freezate (btc_*.json, eth_*.json) │ ├── strategies/ JSON freezate (btc_*.json, eth_*.json)
└── tests/ smoke regression (import + json + schema) │ └── prompts.json v3.2: agent_role/pattern_guidance/instruction/
│ domain_warnings/anti_patterns/output_priorities +
│ 7 stili cognitive (directive + focus_metrics)
└── tests/ smoke regression
``` ```
**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. **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_<asset>/` con lo stesso scheletro (`backend/`, `frontend/`, `strategies/`, `tests/`), DB dedicato `state/strategy_<asset>.db`, servizi Docker `strategy-<asset>-paper` + `strategy-<asset>-gui`, GUI su `/strategy_<asset>_gui`. **Pattern N strategie future:** aggiungere `src/strategy_<asset>/` con stesso scheletro (`backend/`, `frontend/`, `strategies/`, `tests/`, `prompts.json`), DB dedicato `state/strategy_<asset>.db`, servizi Docker `strategy-<asset>-paper` + `strategy-<asset>-gui`, GUI su `/strategy_<asset>_gui`. **Zero modifiche al core** richieste.
## Architettura prompt (v3.2)
**Compositor**: il SYSTEM prompt al LLM viene COMPOSTO at-runtime da scaffold core + contenuto strategy:
```
[1] agent_role ← strategy (prompts.json — chi è l'agente)
[2] cognitive_style + directive ← genome (evoluti dal GA)
[3] GRAMMAR_SPEC ← core scaffold (operatori, indicatori, units rules)
[4] pattern_guidance ← strategy (forme di curva astratte, no indicatori prescritti)
[5] domain_warnings ← strategy (es. "crypto trada 24/7, NON inferire funding rate")
[6] CONSTRAINTS ← core scaffold (validator semantics)
[7] anti_patterns ← strategy (7 voci: no >4 AND, no chattering, isteresi, ecc.)
[8] output_priorities ← strategy (5 voci, #1 coerenza con lente cognitiva)
[9] EXAMPLE ← core scaffold
```
**Input USER (calcolato da `build_market_summary`):**
- Base (5): mean, std, skew, kurt, vol_regime
- Regime recente rolling 500 (6): autocorr_lag1 (recent + baseline), hurst, vol_percentile, seasonality (hour + dow)
- Geometria & frattali (7): efficiency_ratio (Kaufman), tail_index (left + right Hill), structural_uptrend (HH/HL), compression, spectral_entropy, dominant_cycle (gated)
- Feature accessibili dal genome + lookback_window
- **Focus per la tua lente**: blocco style-aware (4 metriche prioritarie da `focus_metrics` di prompts.json)
- Instruction finale (da strategy)
**Grammar protocol JSON (8 indicatori):**
| Indicatore | Output | Range |
|------------|--------|-------|
| `sma(length)` | media mobile | unità prezzo |
| `sma_pct(length)` | (close-sma)/sma | ±0.1 frazione |
| `rsi(length)` | oscillator | 0-100 |
| `atr(length)` | true range | unità prezzo |
| `atr_pct(length)` | atr/close | 0-0.1 frazione |
| `realized_vol(window)` | std returns | 0-0.1 frazione |
| `macd(fast,slow,signal)` | momentum | unità prezzo |
| `macd_pct(...)` | macd/close | ±0.02 frazione |
**7 stili cognitive** (in `prompts.json`, editable): physicist, biologist, historian, meteorologist, engineer, military_strategist, psychologist. Ognuno con directive 800-950 char, ASCII-strict, archetipo dominante + lookback consigliato + 4 focus_metrics.
## Stato del progetto ## 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: **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 in `src/strategy_crypto/strategy_crypto/strategies/`:
- `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). - `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). - `eth_facd6af85d5d.json` — ETH-PERPETUAL, regime-based (con `atr_pct` post-fix bug unità).
Phase 1 → 2.7 chiuse (30 run GA, $3.74 cumulato LLM). Phase 1 → 2.7 chiuse (30 run GA, $3.74 cumulato LLM). Sessione refactor 15 maggio 2026:
- Split repo invertito, monorepo unificato come uv workspace
- Family `*_pct` completa (atr_pct, sma_pct, macd_pct) per fix bug unità
- Dashboard split: core (GA) vs strategy (paper)
- Prompt architecture compositor + prompts.json v3.2 (vedi decision log)
- [**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. Documenti:
- Decision log: [`src/multi_swarm_core/docs/decisions/`](src/multi_swarm_core/docs/decisions/) (gate Phase 1, scelta nemotron). - [**Stato progetto e roadmap (14 maggio 2026)**](src/multi_swarm_core/docs/reports/2026-05-14-stato-progetto-e-roadmap.md)
- Design docs concettuali: [`src/multi_swarm_core/docs/design/`](src/multi_swarm_core/docs/design/). - Decision log: [`src/multi_swarm_core/docs/decisions/`](src/multi_swarm_core/docs/decisions/) (gate Phase 1, nemotron, atr_pct fix)
- 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. 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.
@@ -65,7 +111,7 @@ Stack: Python 3.13, uv workspace, hatchling, pytest+pytest-mock+responses, opena
```bash ```bash
uv sync # installa entrambi i workspace member come editable uv sync # installa entrambi i workspace member come editable
cp .env.example .env # compila CERBERO_*_TOKEN e OPENROUTER_API_KEY cp .env.example .env # compila CERBERO_*_TOKEN e OPENROUTER_API_KEY
uv run pytest # 186 test attesi (182 core + 4 smoke strategy_crypto) uv run pytest # 238 test attesi (234 core + 4 smoke strategy_crypto)
``` ```
### Variabili .env richieste ### Variabili .env richieste
@@ -84,10 +130,9 @@ OPENROUTER_API_KEY=<sk-or-v1-...>
GA_DB_PATH=./state/runs.db GA_DB_PATH=./state/runs.db
STRATEGY_CRYPTO_DB_PATH=./state/strategy_crypto.db STRATEGY_CRYPTO_DB_PATH=./state/strategy_crypto.db
# Deploy Docker # Deploy Docker — DASHBOARD_ROOT_PATH ora per-servizio (vedi docker-compose.yml)
DOMAIN_NAME=tielogic.xyz DOMAIN_NAME=tielogic.xyz
SWARM_DASHBOARD_PORT=8080 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`. Backcompat: `DB_PATH` legacy continua a funzionare come alias di `GA_DB_PATH`.
@@ -113,6 +158,7 @@ uv run python scripts/run_phase1.py \
--end 2026-01-01T00:00:00+00:00 \ --end 2026-01-01T00:00:00+00:00 \
--population-size 20 --n-generations 10 \ --population-size 20 --n-generations 10 \
--prompt-mutation-weight 0.30 --fitness-v2 --prompt-mutation-weight 0.30 --fitness-v2
# Default --prompt-library: importlib.resources del package strategy_crypto/prompts.json
# Backtest standalone di una strategia JSON # Backtest standalone di una strategia JSON
uv run python scripts/backtest_strategy.py \ uv run python scripts/backtest_strategy.py \
@@ -123,32 +169,35 @@ uv run python scripts/backtest_strategy.py \
uv run python scripts/run_paper_trading.py \ uv run python scripts/run_paper_trading.py \
--name phase3-papertrade-XXX \ --name phase3-papertrade-XXX \
--initial-capital 1000 --poll-seconds 300 --initial-capital 1000 --poll-seconds 300
# Default --strategies-dir: importlib.resources del package strategy_crypto
# Dashboard NiceGUI locale # Dashboard NiceGUI locale (2 distinte)
uv run python -m strategy_crypto.frontend.nicegui_app uv run python -m multi_swarm_core.dashboard.nicegui_app # GA core (/, /convergence, /genomes)
# → http://localhost:8080 (env SWARM_DASHBOARD_PORT) uv run python -m strategy_crypto.frontend.nicegui_app # Strategy crypto (/ paper)
``` ```
## Dashboard ## Dashboard (split core + strategy)
NiceGUI dashboard (dark palette) — **dual-DB reader** (GA + paper): Due NiceGUI dashboard distinte (dark palette, palette neon):
**Core GA** — `multi_swarm_core.dashboard.nicegui_app` → `https://swarm.tielogic.xyz/multi_swarm_core_gui/`:
- **Overview** (`/`): lista runs GA, costo cumulato, metriche aggregate evaluations. - **Overview** (`/`): lista runs GA, costo cumulato, metriche aggregate evaluations.
- **GA Convergence** (`/convergence`): fitness median/max/p90 per generazione + entropy. - **GA Convergence** (`/convergence`): fitness median/max/p90 per generazione + entropy.
- **Genomes** (`/genomes`): top-K ordinati per fitness, ispezione system_prompt + JSON strategy. - **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. **Strategy crypto** — `strategy_crypto.frontend.nicegui_app` → `https://swarm.tielogic.xyz/strategy_crypto_gui/`:
- **Paper** (`/`): forward-test live con equity curve, posizioni aperte, trade list, tick log.
In produzione subpath gestiti via `DASHBOARD_ROOT_PATH` (per-servizio) + Traefik `replacepathregex` (NB: NON `stripprefix`, vedi sezione Deploy). La root del dominio resta libera per future GUI di altre strategie.
## Deploy ## Deploy
`docker-compose.yml` definisce due servizi su immagine `multi-swarm-coevolutive:dev`: `docker-compose.yml` definisce 3 servizi su immagine condivisa `multi-swarm-coevolutive:dev`:
- **`strategy-crypto-paper`** — runner `scripts/run_paper_trading.py` long-running. - **`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/`. - **`strategy-crypto-gui`** — NiceGUI paper dashboard su `https://swarm.${DOMAIN_NAME}/strategy_crypto_gui/`.
- **`multi-swarm-core-gui`** — NiceGUI GA dashboard su `https://swarm.${DOMAIN_NAME}/multi_swarm_core_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/`. Persistenza via bind mount: `./data/`, `./series/`, `./state/`. Strategie JSON bind-mounted in read-only dal package: `./src/strategy_crypto/strategy_crypto/strategies/`.
```bash ```bash
docker compose up -d --build docker compose up -d --build
@@ -158,12 +207,16 @@ docker compose ps
Note operative: Note operative:
- Le bind-mount dir devono essere `chown 1000:1000` (uid utente `app` nel container). - Bind-mount dir devono essere `chown 1000:1000` (uid utente `app` nel container). **Anche `src/strategy_crypto/strategy_crypto/strategies/`** (creata da `git mv`, default `root:root`).
- Override del command paper via env (`PAPER_RUN_NAME`, `PAPER_INITIAL_CAPITAL`, ecc.). - 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). - `SWARM_DASHBOARD_PORT` controlla la porta interna del container (Traefik fa il TLS).
- **Traefik subpath**: usa `replacepathregex` middleware (NON `stripprefix`) per evitare doppio root_path (uvicorn legge `X-Forwarded-Prefix` da stripprefix + applica `root_path` di NiceGUI = doppio prefix). Vedi commit `436613b`.
- Dopo cambio label Traefik: `docker restart traefik-traefik-1` per forzare refresh discovery.
## Sviluppo ## 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. 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`. Workspace single-repo, monorepo unificato dal 15 maggio 2026 (split temporaneo monorepo→figlio invertito, vedi tag `v0.1.0-pre-split` come bookmark). 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).
**Modificare il prompt LLM** senza toccare codice: edita `src/strategy_crypto/strategy_crypto/prompts.json`. Schema documentato in `_design_invariants` del JSON stesso. I 3 regression guard test (`test_strategy_crypto_directives_ascii_safe`, `..._have_archetype_marker`, `..._have_lookback_hint`) bloccano regressioni accidentali sulle invarianti di design.