TR_Agent/MQL5/Experts/MultiAgentTest/DOCUMENTAZIONE_COMPLETA.md

Documentazione Completa — MultiAgent TR_Agent EA

Indice

1. MultiAgentTest.mq5
2. Core/Orchestrator.mqh
3. Core/NeuralNet.mqh
4. Core/Statistics.mqh
5. Core/Signal.mqh
6. Core/MarketData.mqh
7. Core/PeriodCalculator.mqh
8. Agents/AgentBase.mqh
9. Agents/MAAgent.mqh
10. Agents/MomentumAgent.mqh
11. Agents/PatternHunter.mqh
12. Agents/RegimeADX.mqh
13. Agents/RegimeConsensus.mqh
14. Agents/RegimeDetector.mqh

---

1. MultiAgentTest.mq5

Scopo

Main EA file: punto d'ingresso di MetaTrader 5. Gestisce OnInit (setup), OnTick (per-barra), OnTrade (chiusure), e OnDeinit (salvataggio e report).

Input Parameters

• Inp_Symbol: Simbolo da tradare (vuoto = simbolo corrente)
• Inp_TF: Timeframe di esecuzione (default = CURRENT = timeframe del chart)
  • Funziona su QUALSIASI timeframe (M1, M5, M15, M30, H1, H4, D1, W1, MN1)
  • I periodi degli agenti (Hurst, MA, Momentum, ADX) si adattano automaticamente
  • Il buffer dati scala con la barra: 300+ barre sono sempre sufficienti
  • L'unica differenza tra timeframes è la granularità degli ingressi
• Inp_Lot: Lotto fisso (sostituito da AdaptiveBaseLot se >0)
• Inp_MinZ: Soglia minima z-score per entrata (0=adattiva)
• Inp_WMin: Peso minimo per agente (0=auto)
• Inp_BufferBars: Barre nel buffer (0=auto)
• Inp_SLRiskATR: SL fisso in ATR (0=adattivo)
• Inp_TPRiskATR: TP fisso in ATR (0=adattivo)
• Inp_HurstPeriod, Inp_ADXPeriod: Periodi fissi (0=auto)
• Inp_UseNeural: True = neural orchestrator, False = softmax classico
• Inp_TrainMode: Colleziona campioni e allena NN in backtest
• Inp_NNHidden: Neuroni hidden layer
• Inp_RiskFraction: Frazione di capitale da rischiare per trade (default 0.20 = 20%)
• Inp_UseReversalClose: Se true, chiude posizioni quando il segnale si inverte. Se false, long e short coesistono

OnInit

1. Legge parametri di mercato (spread, digits, punto)
2. Crea Orchestrator con gli input
3. Crea e registra 6 agenti: RegimeDetector (Hurst), RegimeADX, RegimeConsensus, MAAgent, MomentumAgent, PatternHunter
4. Verifica buffer dati sufficiente
5. Carica modello NN esistente (se Inp_UseNeural)

OnTick

• Lavora su new bar (compare i tempi)
• Prepara MarketData (prezzi, indicatori)
• Chiama orchestrator.Analyze(data) per z-score combinato
• Ottiene FinalSignal da GetFinalSignal()
• Chiama ManagePositions(data, fs) per apertura/chiusura
• Trailing stop su tutte le posizioni

OnTrade

• Rileva trade chiusi da SL/TP (non da reversal)
• Calcola il ritorno in ATR
• Chiama orchestrator.OnTradeClose() che:
  • Aggiorna MAE/MFE stats
  • Colleziona campione NN con peso = |return| + 1
  • Chiama agente Learn() con ritorno normalizzato
  • Aggiorna health (Sharpe rolling)
  • Salva stato ogni saveInterval trade

ManagePositions

1. Update MAE/MFE per tutti gli aperti (intra-barra high/low)
2. TrailStops: muove SL su tutte le posizioni
3. Chiudi posizioni con segnale invertito (reversal)
4. Aggiorna SL sul terminale via PositionModify
5. Apri nuova posizione OGNI BARRA con |z| > minZ (aggressivo multi-position)
   • SL width da AdaptiveSLWidth (MAE-based con EVT fallback)
   • Lotto = AdaptiveBaseLot × |z| (scalato dal segnale)
   • Nessun TP fisso: uscita via trailing stop o reversal

OnDeinit

• Salva: stato agenti, correlazioni, RunningStats, NN (inline)
• Stampa report: PrintAgentStats, PrintNeuralStats, loss history CSV
• Aggiorna summary

Principi Chiave

• Multi-position: ogni barra con segnale apre UNA NUOVA posizione
• Nessun TP fisso: uscita via reversal o trailing stop
• SL adattivo: da distribuzione MAE dei trade vincenti
• Training online: campioni collezionati in backtest, NN allenata in OnDeinit

---

2. Core/Orchestrator.mqh

Scopo

Cervello del sistema: orchestrazione agenti, combinazione z-score, gestione multi-position, trailing stop, training NN, stato persistente.

Strutture Dati

TrackedTrade: traccia ogni posizione aperta:

• ticket, entryPrice, entryATR, entryZ, slPrice, isBuy
• highestPrice, lowestPrice (per MAE/MFE tracking)
• maeATR, mfeATR (massimo movimento avverso/favorevole in ATR)
• barsHeld, active
• entryFeatures[NN_FEATURES] (per training NN)
• entryZScores[MAX_AGENTS] (per agent learning)

BarSnapshot: cache storica per autocorrelazione:

• combinedZ, timestamp

Membri Principali

• agents[MAX_AGENTS]: array di IAgent*
• combinedZ: z-score combinato pesato
• agentWeights[MAX_AGENTS]: pesi EWMA basati su correlazione
• corrMeanX/Y, corrCov, corrVarX/Y: RunningCorrelation per coppia agente-combinedZ
• returnStats, combinedZStats, maeStats, mfeStats, maeWinStats: distribuzioni empiriche
• openTrades[maxOpenTrades]: tutte le posizioni aperte
• m_neuralNet, m_trainBuffer: rete neurale e buffer training
• m_riskFraction: frazione di capitale da rischiare (default 20%)
• rollingReturns[ROLLING_TRADES]: per Sharpe rolling

Metodi Principali

AddAgent: registra agente, inizializza correlazioni, ri-inizializza RunningStats con alpha/min derivati da agentCount.

Analyze (fase 1-3):

1. Aggrega: raccoglie z-score da tutti gli agenti
2. Interact: agenti leggono z-score altrui (via SHARED_)
3. Combina: pesi EWMA basati su correlazione agente-combinedZ, softmax con temperatura adattiva (o NN)

OnTradeOpen: registra nuova posizione in openTracks[], copia entryZScores ed entryFeatures

OnTradeClose:

• Calcola ritorno in ATR
• Aggiorna MAE/MFE stats
• Colleziona training sample NN con peso = |return| + 1
• Chiama agent.Learn() per auto-calibrazione
• Aggiorna rolling Sharpe
• Salva stato ogni saveInterval

UpdateOpenTrades: per ogni barra, aggiorna MAE/MFE da high/low

TrailStops: implementa trailing stop:

• Calcola trail trigger da MFE mean (o EVT fallback)
• Calcola trail offset da MAE win mean (o EVT fallback)
• Se profitto > trigger, muove SL a entry ± (profitto - offset)

AdaptiveSLWidth: SL width da MAE distribuzione:

• Fallback: combinedZStats.Std() × sqrt(N) o EVT_SL
• Con dati: max(fallback, maeWinStats.Mean() + maeWinStats.Std())

AdaptiveTrailTrigger: da MFE mean (o EVT) AdaptiveTrailOffset: da MAE win mean (o EVT)

AdaptiveMinZ: soglia entrata = StdErr(combinedZ) = Std/sqrt(N) — bassa per trading frequente

AdaptiveBaseLot: lotto = balance × riskFraction / 100000 — chiamante scala per |z|

GetTradesToClose: reversal detection: buy chiusi se currentZ < -minZ, sell se > minZ

SaveState / LoadState (v6):

• Salva: versione, agenti (pesi, bias, predError, predCorr, lastZScore), correlazioni, RunningStats, NN
• NN salvato inline (handle file embedded)
• Carica: stessi campi, ripristino buffer NN

TrainNN: allena CNeuralNet con buffer campioni, pesi per sample importance

InitNeuralNet: configura architettura NN, inizializza He con iperparametri derivati:

• dropout = 1/sqrt(hidden)
• L2 = 1/max(totalParams, 100)
• β₁ = 1 − 1/max(hidden, 10)
• β₂ = 1 − 1/max(hidden×100, 1000)
• BN momentum = 1 − 1/max(hidden×5, 50)
• BN ε = DATA_EPS(1.0)

Principi Chiave

• Zero magic constants: ogni soglia derivata da distribuzioni empiriche o EVT
• Multi-position aggressivo: ogni barra con segnale apre posizione
• Trailing stop adattivo: MAE/MFE guidano trigger e offset
• NN opzionale: cade a softmax se non inizializzata
• Persistenza: tutto (incluso NN) salvato inline in file stato

---

3. Core/NeuralNet.mqh

Scopo

Rete neurale feed-forward: 1 hidden layer ReLU, dropout, BatchNorm, Softmax output, Adam optimizer. Training online con batch_size=1 per compatibilità MT5.

Architettura

• Input → W1 (fanIn×hidden) + b1 → ReLU → Dropout → BatchNorm → W2 (hidden×3) + b2 → Softmax
• Output: [P(Buy), P(Flat), P(Sell)]
• Hidden size: input Inp_NNHidden (default 6)

CNeuralNet

Inizializzazione: He Init sqrt(6/fanIn) per ReLU.

Forward:

1. z1 = W1×x + b1 → ReLU(z1) → h1
2. Dropout: mask binaria con probabilità 1-dropoutRate
3. BatchNorm (train): EMA runningMean/runningVar, gamma/beta learnable
4. z2 = W2×h1_norm + b2 → Softmax → output [0,1]³

Loss: CCE (Cross-Entropy) pesata + L2:

• L = -Σ weight × target_i × log(p_i) + 0.5×L2×(∥W1∥² + ∥W2∥²)

Backward (Adam):

• dL/dz2 = weight × (output − target) (CCE+Softmax combinata)
• dL/dW2 = h1_normᵀ × dL/dz2
• dL/dh1_norm = W2 × dL/dz2
• BNBackward: dL/dh1_drop = gamma/sqrt(var) × dL/dh1_norm
• Dropout backward: passa gradiente solo dove mask=1
• dL/dz1 = dL/dh1_raw ⊙ ReLU'(z1)
• dL/dW1 = xᵀ × dL/dz1
• Adam update per W1, b1, W2, b2, bnGamma, bnBeta

Iperparametri architettura-derivati (zero magic constants):

• dropout = 1/sqrt(hidden)
• L2 = 1/max(totalParams, 100)
• β₁ = 1 − 1/max(hidden, 10)
• β₂ = 1 − 1/max(hidden×100, 1000)
• ε = DATA_EPS(1.0)
• BN momentum = 1 − 1/max(hidden×5, 50)
• BN ε = DATA_EPS(1.0)

Save/Load v3: pesi salvati in formato binario compatto, inline nello stato.

LossHistory: array epoch-loss, dump CSV.

NNTrainBuffer

Buffer circolare di campioni per training NN.

Struttura: NNTrainSample { features[8], target[3], weight }.

Metodi:

• Add(features, target, weight): aggiunge campione
• Trim(maxSamples): rimuove i più vecchi
• ToMatrices(features, targets): esporta per training
• GetWeights(): vettore dei pesi campione
• SaveCsv(filename): dump per debug
• PrintStats/PrintFeatureStats: diagnostica dataset

Principi Chiave

• Batch size = 1: forzato da MT5, BN usa running stats non batch stats
• Loss pesata: trade con grande impatto pesano di più nel training
• Inline nel file stato: NN salvato dentro .model per portabilità tester→live
• Zero magic: dropout, L2, β₁, β₂, ε, BN momentum/ε tutti derivati

---

4. Core/Statistics.mqh

Scopo

Statistiche in tempo reale: EWMA, RunningStats (media/variance online), RunningCorrelation, DATA_EPS.

DATA_EPS(x)

• MathMax(MathSqrt(DBL_EPS), MathAbs(x) * MathSqrt(DBL_EPS))
• Soglia floating-point di qualità: scala con la magnitudine dei dati
• Radice quadrata del DBL_EPS standard (≈1.49e-8), non epsilon assoluto 1e-15

EWMA

EWMA univariato con fattore α:

• mean += α × (x − mean)
• var = (1−α) × (var + α × (x−mean)²) (metodo di Finch)

RunningStats

Media e varianza online con EWMA:

• alpha = 1/(N_agenti × 10), minSamples = N_agenti × 5
• Count(), Mean(), Std(), Var(), Skew()
• Ready(): count >= minSamples
• Save/Load: formato binario

RunningCorrelation

Correlazione online tra due variabili:

• Stessa logica EWMA di RunningStats
• Update(x, y), Correlation(), Count(), Ready()
• Utilizzata per: correlazione agente-combinedZ, weight update

Funzioni EVT

• EVT_MaxAbsZ(N) = sqrt(2 × log(2 × N)): expected maximum |z| di N gaussiane
• RStatsAlpha() = 1.0 / max(agentCount × 10, 10)
• RStatsMinSamp() = max(agentCount × 5, 10)

Principi Chiave

• Online: tutte le statistiche sono incrementali, nessun buffer storico
• EWMA: pesa più i dati recenti
• DATA_EPS: soglia scalabile, non epsilon assoluto
• EVT: Extreme Value Theory per fallback senza dati

---

5. Core/Signal.mqh

Scopo

Strutture dati di segnale e stato.

FinalSignal

Rappresenta il segnale finale dopo orchestrazione:

• direction: +1 (Buy), -1 (Sell), 0 (Flat)
• zScore: z-score combinato (firmato)
• totalAgents: numero agenti attivi
• agreeingCount: quanti agenti concordano con direzione
• contributingAgents: stringa nomi agenti concordanti

TrackedTrade

Rappresenta una posizione aperta tracciata:

• ticket, entryPrice, entryATR, entryZ, slPrice, isBuy
• highestPrice, lowestPrice: per MAE/MFE intra-barra
• maeATR, mfeATR: massimo movimento avverso/favorevole in ATR
• barsHeld: barre da apertura
• active: true se posizione ancora aperta
• entryFeatures[8]: feature snapshot all'apertura (per NN)
• entryZScores[MAX_AGENTS]: z-score agenti all'apertura (per learning)

BarSnapshot

• combinedZ, timestamp: per calcolo autocorrelazione

Principi Chiave

• TrackedTrade è auto-contenuta: porta tutto ciò che serve per learning e training
• Multi-position: array di TrackedTrade fino a maxOpenTrades

---

6. Core/MarketData.mqh

Scopo

Fornitore dati di mercato: prezzi, spread, indicatori nativi MT5.

MarketData

• Symbol() / Timeframe()
• High(shift), Low(shift), Close(shift), Open(shift)
• Spread(): spread corrente in punti
• ATR(period): iATR nativo
• ATR(period, shift): iATR con shift
• Ma(period, shift, method, applied): iMA nativo
• Momentum(period, shift): iMomentum nativo
• ADX(period, shift): iADX nativo (Main, PlusDI, MinusDI)

Principi Chiave

• Indicatori nativi MT5: iMA, iATR, iMomentum, iADX — nessuna implementazione custom
• Cache: i valori sono calcolati su richiesta con handle MT5
• ATR period derivato: max(N+1, min(buffer/15, 50)) — scala con agenti e buffer

---

7. Core/PeriodCalculator.mqh

Scopo

Calcolo dei periodi adattivi per ogni agente.

Funzioni

• HurstPeriod(bufferBars, hurstPeriodInput): periodo per calcolo Hurst
• ADXPeriod(bufferBars, adxPeriodInput): periodo per ADX
• MAPeriod(bufferBars, ...): periodo per MA
• MomentumPeriod(bufferBars, ...): periodo per Momentum

Ogni funzione:

• Se input > 0: usa input fisso
• Se input = 0: calcola da bufferBars usando formula adattiva

---

8. Agents/AgentBase.mqh

Scopo

Classe base astratta per tutti gli agenti. Definisce interfaccia, stato persistente, meccanismi di calibrazione.

IAgent (interfaccia)

virtual void   Analyze(MarketData&) = 0;
virtual void   Learn(double actualReturn) = 0;
virtual double GetZScore() = 0;

Membro

• name, enabled, weight, lastZScore
• predictionError: RunningStats dell'errore di predizione (bias)
• predCorr: RunningCorrelation tra predetto e reale
• combinedZStats: RunningStats locale per normalizzare z-score

AgentBase (implementazione parziale)

CalibrateZ(z): normalizza z-score usando combinedZStats locale:

• Se ha dati: z_score = (z − mean) / std
• Se non ha dati: z_score = z / EVT_MaxAbsZ(max(2N, 2))

Learn(actualReturn, subSignals):

• Calcola predictionError: differenza tra lastZScore e actualReturn normalizzato
• Aggiorna predCorr: correla lastZScore con actualReturn
• Tutti gli agenti ereditano questo comportamento

Save/Load v3: salva nome, peso, lastZScore, predictionError, predCorr, combinedZStats.

Principi Chiave

• Auto-calibrazione: ogni agente normalizza i propri z-score
• Autovalutazione: predictionError (bias) + predCorr (allineamento direzionale)
• Zero magic: fallback EVT per normalizzazione

---

9. Agents/MAAgent.mqh

Scopo

Agente Moving Average: confronta prezzo corrente con MA per generare z-score.

Funzionamento

1. Calcola MA a periodo adattivo (iMA nativo)
2. Prezzo relativo: (close − MA) / ATR
3. Normalizza via CalibrateZ() per produrre z-score ~N(0,1)
4. Learn(): traccia sub-signals priceToMaCorr e slopeCorr

Sub-signals

• priceToMaCorr: RunningCorrelation tra (close-MA)/ATR e ritorno
• slopeCorr: RunningCorrelation tra pendenza MA e ritorno

Output

• Z-score positivo: prezzo sopra MA (trend rialzista)
• Z-score negativo: prezzo sotto MA (trend ribassista)
• Segnale tanto più forte quanto più il prezzo è lontano dalla MA (in ATR)

Principi Chiave

• MA period adattivo: da PeriodCalculator
• Unità ATR: normalizza la distanza prezzo-MA in termini di volatilità
• Auto-calibrazione: CalibrateZ mantiene output ~N(0,1)
• Apprendimento: traccia correlazione sub-signals per miglioramento

---

10. Agents/MomentumAgent.mqh

Scopo

Agente Momentum: cattura accelerazione del prezzo via iMomentum nativo.

Funzionamento

1. Calcola Momentum = iMomentum(period) = close − close[period-1]
2. Momento normalizzato: momentum / ATR (in unità di volatilità)
3. Seconde differenze per accelerazione: momentum − momentum[shift]
4. Combina momentum + accel con RunningStats pesato
5. CalibrateZ() per z-score finale

Sub-signals

• momCorr: RunningCorrelation tra momentum e ritorno
• accelCorr: RunningCorrelation tra accelerazione e ritorno

Output

• Z-score positivo: momentum positivo (trend in accelerazione)
• Z-score negativo: momentum negativo
• Pesa accelerazione quando ha alta correlazione col ritorno

Principi Chiave

• iMomentum nativo MT5: no implementazione custom
• Doppio segnale: momentum + accelerazione
• Adattivo: peso accelerazione basato su correlazione storica

---

11. Agents/PatternHunter.mqh

Scopo

Agente di pattern recognition cross-agente: identifica pattern negli z-score degli altri agenti.

Funzionamento

1. Analizza z-score di tutti gli agenti (da SHARED_ variabili)
2. Classifica pattern in codici -10..+10:
   • Pattern di accordo: tutti concordi (z-std basso)
   • Pattern di divergenza: agenti divisi (z-std alto)
   • Pattern di reversal: cambio direzione rispetto a barra precedente
   • Pattern di momentum: accelerazione/decelerazione
3. Ogni pattern code ha RunningStats locale (patternStats[code+10])
4. Z-score = winRate del pattern corrente (CalibrateZ normalizza)

Learn()

• patternStats[patternCode+10] aggiornato con esito trade
• Traccia win rate per ogni pattern

Output

• Timeframe lungo: convergenza/dominanza di certi pattern
• Z-score positivo: pattern storicamente vincente per Buy
• Z-score negativo: pattern storicamente vincente per Sell

Principi Chiave

• Cross-agente: non guarda il prezzo ma il comportamento degli altri agenti
• Pattern statistics: ogni pattern ha RunningStats di performance
• Auto-apprendimento: più trade → migliori stime win rate per pattern

---

12. Agents/RegimeADX.mqh

Scopo

Agente di regime basato su ADX: rileva trend vs range tramite iADX nativo.

Funzionamento

1. iADX(period, shift): ADX Main, +DI, -DI
2. Regime score = (+DI − -DI) / ADX_Main (direzione normalizzata per forza trend)
3. CalibrateZ() per output ~N(0,1)

Output

• Z-score positivo: +DI > -DI → trend rialzista
• Z-score negativo: -DI > +DI → trend ribassista
• Magnitudo: forza del trend (ADX alto) + direzionalità

Principi Chiave

• iADX nativo MT5: no implementazione custom
• Unità di forza trend: regime score normalizzato da ADX
• Risposta rapida: reagisce a cambiamenti di regime DI

---

13. Agents/RegimeConsensus.mqh

Scopo

Agente di consenso: combina Hurst + ADX per determinazione robusta del regime.

Funzionamento

1. Legge Hurst da RegimeDetector (via SHARED_)
2. Legge ADX da RegimeADX (via SHARED_)
3. Consensus score = peso × Hurst + (1-peso) × ADX
4. Peso da RunningStats della correlazione di ciascuno col ritorno
5. CalibrateZ() per output finale

Learn()

• Sub-signals: hurstCorr (corr Hurst-ritorno), adxCorr (corr ADX-ritorno)
• Aggiorna pesi basati su correlazione storica

Output

• Z-score positivo: regime identificato come trend rialzista
• Z-score negativo: regime trend ribassista
• Zero: regime incerto (Hurst range-bound + ADX basso)

Principi Chiave

• Consenso multi-regime: Hurst + ADX complementari
• Pesi adattivi: aggiornati via Learn() basato su performance
• Stabilità: consenso filtra falsi segnali di un singolo regime detector

---

14. Agents/RegimeDetector.mqh

Scopo

Agente di detection basato su Hurst Exponent: misura tendenza al trend/mean-reversion del mercato.

Funzionamento

1. Hurst via DFA (Detrended Fluctuation Analysis) con fallback R/S
2. Hurst = 0.5 → random walk
3. Hurst > 0.5 → trending (buy quando close sopra MA, sell sotto)
4. Hurst < 0.5 → mean-reverting (buy quando close sotto MA, sell sopra)
5. Z-score = (Hurst - 0.5) × factor × (close-MA)/ATR
6. CalibrateZ() per output finale

DFA Algorithm

1. Prezzo logaritmico: y_i = log(close_i)
2. Trend locale: sottrai media su finestra mobile
3. Fluttuazione: RMS dei residui
4. Hurst = log(F(n) / F(n/2)) / log(2)

Fallback R/S

• Se DFA fallisce (dati insufficienti): R/S classico
• Range = max(cumsum) − min(cumsum)
• R/S = range / std dei log-returns

Output

• Z-score positivo: mercato trending rialzista
• Z-score negativo: mercato trending ribassista
• Magnitudo: forza del fenomeno (quanto Hurst si discosta da 0.5 × forza trend)

Principi Chiave

• Implementazione manuale: nessun indicatore nativo (Hurst non esiste in MT5)
• DFA primario, R/S fallback: robustezza
• Direzionalità: combina Hurst con posizione prezzo-MA
• Lento ma fondamentale: identifica regime macro, non trading frequency

---

Filosofia Generale del Sistema

Multi-Agente con Orchestrazione Neurale

6 agenti specializzati producono z-score normalizzati ~N(0,1). L'orchestratore combina:

• Classic: pesi EWMA basati su correlazione storica + softmax con temperatura adattiva
• Neural: CNeuralNet che impara la combinazione non-lineare ottimale

Zero Magic Constants

Ogni numero nel sistema è derivato da:

• Distribuzioni empiriche: RunningStats di MAE/MFE/ritorni
• EVT (Extreme Value Theory): fallback senza dati per SL, trigger, offset
• Architettura NN: dropout, L2, β₁, β₂, ε da hidden size
• Floating-point standard: sqrt(DBL_EPS) per soglie numeriche
• Statistica classica: StdErr, correlazioni, Student-t

Multi-Position Aggressivo

• Ogni barra con segnale apre nuova posizione
• 20% di capitale per trade (configurabile)
• Nessun TP fisso: trailing stop adattivo da MFE/MAE
• SL width da MAE dei trade vincenti

Apprendimento Continuo

• Agenti: CalibrateZ() + Learn() con bias/correlation tracking
• NN: training supervisionato con campioni pesati per importanza
• Stato: tutto salvato inline (incluso NN) per portabilità tester→live

---

15. Trade Entry / Exit Logic

Come Entra a Mercato

L'entry avviene in ManagePositions() in MultiAgentTest.mq5, ogni barra con segnale actionable:

1. Nuova barra rilevata in OnTick → chiama orchestrator.Analyze(data) per produrre combinedZ
2. GetFinalSignal() produce FinalSignal { direction, zScore, ... }
3. Controllo soglia: se |zScore| > minZ (dove minZ = AdaptiveMinZ()), si procede
4. Calcolo SL: SL = price ± atr × slWidth dove slWidth = AdaptiveSLWidth()
5. Calcolo lotto: lot = AdaptiveBaseLot() × |zScore|
   • AdaptiveBaseLot() = balance × riskFraction / 100000
   • Con riskFraction = 0.20 (20%): per $10k → lotto base 0.20 × z
6. Chiamata MT5: trade.Buy(lot, sym, ask, sl, 0) o trade.Sell(lot, sym, bid, sl, 0)
   • TP = 0: nessun take profit fisso, l'uscita è gestita da trailing stop o reversal
7. Tracciamento: orchestrator.OnTradeOpen(ticket, price, atr) salva la posizione in openTrades[]

Frequenza di Entry (Multi-Position)

• Ogni barra con segnale apre UNA NUOVA posizione, indipendentemente da quante sono già aperte
• Solo il margine libero limita il numero di posizioni: se marginReq ≥ freeMargin, il trade è saltato
• Nessun limite artificiale: l'array openTrades[] cresce dinamicamente (EnsureTradeCapacity)
• Con AdaptiveMinZ = Std/sqrt(N) (~0.16 con 6 agenti), la soglia è molto bassa → molte entrate
• Il sistema può gestire centinaia di posizioni contemporanee se il margine lo permette

Come Esce a Mercato

Ci sono tre modi per chiudere una posizione:

A) Reversal (chiusura attiva) — OPZIONALE

• Controllato da Inp_UseReversalClose (default: true)
• Se true: in ManagePositions(), dopo aver calcolato il nuovo segnale:
  • GetTradesToClose() ritorna i ticket delle posizioni con direzione opposta al segnale corrente
  • BUY chiusi se currentZ < -minZ, SELL chiusi se currentZ > minZ
  • Chiamata: OnTradeClose(tkt, closePrice) + trade.PositionClose(tkt)
• Se false: le posizioni NON vengono mai chiuse per reversal. Ogni barra apre UNA NUOVA posizione nella direzione del segnale, e le posizioni esistenti rimangono aperte. Questo permette:
  • Long e short simultanei: il sistema può tenere posizioni in entrambe le direzioni
  • Massimizzazione del profitto: non taglia le posizioni che potrebbero ancora essere redditizie
  • Uscita solo via trailing stop o SL: nessuna chiusura "forzata" dal segnale
  • Attenzione: il rischio aumenta perché le posizioni opposte si compensano parzialmente

B) Trailing Stop (chiusura automatica)

• In TrailStops(), chiamato ogni barra:
  1. Calcola trail trigger: da AdaptiveTrailTrigger() = MFE medio o EVT fallback
  2. Calcola trail offset: da AdaptiveTrailOffset() = MAE medio dei vincenti o EVT fallback
  3. Se il profitto corrente > trail trigger (in ATR):
     • BUY: newSL = entryPrice + (highestPrice - entryPrice) - offset
     • SELL: newSL = entryPrice - (entryPrice - lowestPrice) + offset
  4. Se il nuovo SL è più stretto del precedente, viene aggiornato via PositionModify(tkt, newSL, curTP)
• Il trailing stop si attiva SOLO dopo che il prezzo ha superato il tipico MFE

C) SL/TP iniziale (broker-side)

• All'apertura, ogni posizione ha uno stop loss (SL = price ± atr × slWidth)
• Se il mercato va contro la posizione, lo SL iniziale ferma la perdita
• La chiusura da SL/TP è rilevata in OnTrade(): se un ticket tracciato non è più in PositionsTotal(), viene chiamato OnTradeClose()
• Il trailing stop può spostare lo SL per proteggere i profitti, ma non lo allarga mai

Numero di Ordini

• Entrate: 1 posizione per barra con segnale (potenzialmente centinaia al giorno su M1)
• Uscite: 1 chiusura per posizione (via reversal, trailing, o SL)
• Modifiche: 1 modifica per barra per posizione (trailing SL via PositionModify)
• Totale ordini: dipende dalla frequenza dei segnali × numero posizioni aperte
• In backtest su H1 con 6 agenti: tipicamente 50-200 trade/mese, ma con entry aggressive può essere molto di più

---

16. Risk Management

Dimensionamento Posizione

Il rischio per trade è controllato da due livelli:

Livello 1: Frazione di Capitale (Inp_RiskFraction)

• Default: 0.20 (20% del capitale per trade)
• lotto = balance × riskFraction / 100000 × |z|
• Esempio: $10,000 × 0.20 / 100000 × |z=1.0| = 0.02 lotti (= 2,000 unità EURUSD)
• Il |z| scala il lotto in base alla forza del segnale (|z|=2 → lotto doppio)

Livello 2: Stop Loss Iniziale

• SL = prezzo ± atr × slWidth
• slWidth = AdaptiveSLWidth(): usa MAE dei trade vincenti (o EVT fallback)
• Maggiore slWidth → stop più largo → maggiore rischio per trade
• Il trailing stop protegge ulteriormente spostando lo SL in profitto

Livello 3: Margine

• Controllo esplicito: if(marginReq ≥ freeMargin) return
• Se non c'è abbastanza margine per il lotto calcolato, il trade è saltato
• Questo è l'UNICO limite reale al numero di posizioni

Distribuzione del Rischio (Multi-Position)

Con multi-position:

• Ogni posizione ha rischio individuale = balance × riskFraction × |z| / 100000
• Con 10 posizioni contemporanee: rischio totale = 10 × 0.20 × |z_medio| / 100000 × balance
• Il rischio totale è proporzionale a: Σ|z_i| × riskFraction × balance / 100000
• La diversificazione tra N posizioni riduce il rischio specifico di ogni entry

Drawdown Control

Il sistema non ha un hard stop sul drawdown (per scelta: l'utente vuole trading aggressivo). Tuttavia:

• Il trailing stop limita le perdite di ogni singola posizione
• La distribuzione MAE dei vincenti guida la larghezza dello SL
• Il rollingSharpe negativo è segnalato ma non blocca il trading

---

17. Manual Override System

Anche se il sistema è progettato per essere "zero magic constants" con tutti i valori derivati dai dati, puoi sovrascrivere manualmente qualsiasi parametro tramite gli input dell'EA:

Cosa si può sovrascrivere

Input	Default	Descrizione
Inp_MinZ	0.0 (auto)	Soglia minima z-score. Se >0, ignora AdaptiveMinZ()
Inp_WMin	0.0 (auto)	Peso minimo per agente. Se >0, ignora 1/(N×sqrt(N))
Inp_SLRiskATR	0.0 (auto)	SL fisso in ATR. Se >0, ignora AdaptiveSLWidth()
Inp_TPRiskATR	0.0 (auto)	TP fisso in ATR. (TP=0 = trailing stop puro)
Inp_HurstPeriod	0 (auto)	Periodo Hurst fisso. Se >0, ignora calcolo adattivo
Inp_ADXPeriod	0 (auto)	Periodo ADX fisso. Se >0, ignora calcolo adattivo
Inp_Lot	0.01	Lotto fisso. Sostituisce AdaptiveBaseLot() se >0
Inp_BufferBars	0 (auto)	Numero barre buffer. Se 0: max(300, HurstPeriod×10)
Inp_RiskFraction	0.20	Frazione di capitale per trade. Puoi abbassare (0.05=5%) o alzare (0.50=50%)
Inp_UseNeural	false	True = neural orchestrator, False = softmax classico
Inp_TrainMode	false	Colleziona campioni e allena NN in backtest
Inp_NNHidden	6	Neuroni hidden layer della NN
Inp_UseReversalClose	true	true=chiudi su segnale opposto, false=long+short coesistono

Come funziona l'override

Nel codice, ogni input segue il pattern:

// Se input > 0, usa input. Se = 0, usa valore adattivo
double minZ = (Inp_MinZ > 0) ? Inp_MinZ : orchestrator.AdaptiveMinZ();

Oppure per parametri non-zero:

// NN: se passato >= 0, override
if(l2 >= 0) m_l2 = l2;
if(dropoutRate >= 0) m_dropoutRate = dropoutRate;

Esempi Pratici

Scenario conservativo: Inp_RiskFraction=0.05, Inp_MinZ=1.0

• Rischia 5% per trade, soglia alta → pochi trade selezionati

Scenario aggressivo: Inp_RiskFraction=0.50, Inp_MinZ=0

• Rischia 50% per trade, soglia adattiva bassa → trade frequenti e grandi

Scenario fisso: Inp_SLRiskATR=2.0, Inp_Lot=0.10

• SL sempre a 2 ATR, lotto fisso 0.10 — nessun adattamento

Cosa NON si può sovrascrivere (rimane data-driven)

• RunningStats alpha/min: derivati da N agenti
• NN iperparametri: dropout, L2, β₁, β₂, ε — derivati dall'architettura
• MAE/MFE distribuzioni: sempre empiriche
• EVT fallback: solo quando non ci sono dati
• Correlazioni e pesi: sempre empirici

---

18. Dati Salvati per Analisi Periodica

Alla fine del backtest (OnDeinit), il sistema salva MOLTEPLICI file per analisi approfondita:

File Salvati

File	Contenuto	Cartella
TR_Agent_Analysis_SYMBOL_TF.csv	TUTTI i parametri derivati, soglie, periodi, stats	Common
TR_Agent_NN_v1.dat	Modello NN con pesi inline	Common
NN_TrainingSamples_SYMBOL_TF.csv	Campioni di training (8 feature + target)	Common
NN_LossHistory_SYMBOL_TF.csv	Loss per epoca di training	Common
AgentLearning_SYMBOL_TF.csv	Bias, correlazioni, errori per ogni agente	Common

Contenuto del CSV di Analisi (SaveAnalysisCSV)

Il file TR_Agent_Analysis_SYMBOL_TF.csv contiene TUTTO:

Sezione 1: Trade Statistics

• TotalTrades, WinCount, WinRate, MaxDrawdown, RollingSharpe
• ReturnMean, ReturnStd, ReturnCount
• CombinedZMean, CombinedZStd, CombinedZCount

Sezione 2: MAE/MFE Distributions

• MAE_Mean, MAE_Std (massimo movimento avverso)
• MFE_Mean, MFE_Std (massimo movimento favorevole)
• MAE_Win_Mean, MAE_Win_Std (MAE dei soli vincenti)

Sezione 3: Derived Thresholds

• MinZ (soglia di entrata usata)
• SLWidth (larghezza SL in ATR)
• TrailTrigger (quando si attiva il trailing)
• TrailOffset (quanto si arretra lo SL)
• BaseLot (lotto base calcolato)
• CorrMinSamples, WeightMin, WeightAlpha
• EVT_MaxAbsZ

Sezione 4: Agent Details

• Per ogni agente: Name, Weight, Rho (correlazione), LastZ, Bias, BiasN, RhoLearn, RhoLearnN

Sezione 5: Neural Network

• NN_Epochs, NN_Loss, NN_Arch, NN_LR

Sezione 6: Input Parameters (per poter replicare il backtest)

• Tutti gli Inp_ parametri come sono stati usati

Periodicità del Salvataggio

• Stato modello: salvato ogni saveInterval = N × 5 trade chiusi da SL/TP
• Analisi CSV: salvata UNA volta in OnDeinit
• Agent Learning CSV: salvato UNA volta in OnDeinit
• NN auto-save: ogni 50 campioni durante il training (se TrainMode)
• NN Loss CSV: salvato dopo ogni training in OnDeinit

Come Usare i CSV per Analisi

1. Dopo backtest: apri Common\TR_Agent_Analysis_SYMBOL_TF.csv in Excel/Google Sheets
2. Controlla: Sharpe, Win Rate, Max Drawdown, MAE/MFE
3. Confronta soglie derivate tra backtest diversi per vedere l'evoluzione
4. Usa NN_TrainingSamples_SYMBOL_TF.csv per analizzare la distribuzione delle feature
5. Confronta NN_LossHistory per verificare che la loss scenda durante il training
6. Porta il .dat in live e ricarica lo stato esattamente com'era in backtest