FORGE — Riferimento completo dei configuratori

Tutti i configuratori di FORGE sono dataclass Python standard: mutabili dopo l'istanziazione, componibili per nesting e dotati di default calibrati su dati crypto 1H liquidi. Non è necessario specificare tutti i parametri: l'utente tocca solo ciò che vuole cambiare rispetto ai default. I configuratori di alto livello (es. MarketContextConfig, DiscoveryConfig, RuleDiscoveryConfig) accettano i sotto-configuratori come argomenti nidificati, seguendo esattamente la gerarchia descritta in questo documento.

Modulo 0

EMAProxyConfig

Configura il classificatore EMA-proxy: sorgente dati, calcolo automatico delle finestre, soglie di regime e calibrazione adattiva. Viene passato come campo ema_proxy di MarketContextConfig.

from forgedge import MarketContext, MarketContextConfig, EMAProxyConfig

config = MarketContextConfig(
    ema_proxy=EMAProxyConfig(
        auto_window=True,
        window_unit="day",
        bar_hours=4.0,                # candele da 4H
        threshold_mode="balanced",
        target_distribution=[0.10, 0.20, 0.40, 0.20, 0.10],
        threshold_basis="expanding",  # causale, no look-ahead
    )
)

MarketContextConfig

Contenitore di primo livello per la configurazione del Modulo 0. Aggrega la scelta del classificatore, i suoi parametri e le opzioni di stabilità del regime.

from forgedge import MarketContext, MarketContextConfig, EMAProxyConfig

enriched = MarketContext(
    kpi,
    config=MarketContextConfig(
        stable_window=6,          # più reattivo al cambio di regime
        ema_proxy=EMAProxyConfig(
            auto_window=True,
            window_unit="day",
            bar_hours=1.0,
        ),
    ),
).run()

Modulo 1

GateParams

Soglie del ConsistencyGate — il filtro strutturale che verifica se un evento ha struttura temporale stabile. Viene passato come campo gate_params di DiscoveryConfig.

Dall'issue #134 il gate opera in una di due modalità di conteggio, selezionate da event_counting: "episode" (default) conta i run massimali di attivazioni consecutive invece delle barre grezze, così uno stato persistente multi-barra (un tratto di 3–5 barre con RSI < 30) non viene penalizzato come se fossero più trigger indipendenti; "bar" riproduce esattamente il conteggio pre-#134, barra per barra. Le due modalità coincidono per gli eventi impulsivi (crossover, pattern candlestick — un episodio per barra).

La doppia modalità cambia quale campo di dispersione legge davvero il gate (issue #205): max_dispersion è la soglia grezza sull'Index of Dispersion, ma viene letta solo in modalità "bar". In modalità "episode" il gate confronta invece contro poisson_floor(n_months) × dispersion_margin — un margine sopra il floor statisticamente difendibile di Poisson, non un ID assoluto — perché il floor dominava quasi sempre un max_dispersion fisso in pratica (misurato: 12 combinazioni preset×timeframe su 16 non avevano mai max_dispersion vincolante). Quindi con il default event_counting="episode" va calibrato dispersion_margin, non max_dispersion.

from forgedge import DiscoveryConfig
from forgedge.event_discovery.models import GateParams

config = DiscoveryConfig(
    gate_params=GateParams(
        min_tpm=0.3,             # meno restrittivo per dataset più corti
        dispersion_margin=1.6,   # più margine sopra il floor di Poisson
        min_episodes=5,
        event_counting="episode",  # default; "bar" riproduce il comportamento pre-#134
    )
)

# Opt-in: rigetta anche gli eventi che si attivano troppo spesso, non solo troppo raramente
ranged_config = DiscoveryConfig(
    gate_params=GateParams(tpm_mode="ranged", min_tpm=4.0, tpm_tolerance=2.0)  # banda = [2.0, 6.0]
)

I campi sopra hanno sostituito uno schema GateParams(min_act, min_months, max_conc, min_tpm) più vecchio; nessuno tra min_act/min_months/ max_conc esiste più, e costruire GateParams con questi nomi solleva oggi un TypeError. Alcuni script examples/*.py di questo repo usano ancora lo schema vecchio — vedi la lista dei pitfall della skill forgedge prima di copiarli.

EventWalkForwardConfig (Modulo 1)

Configura la validazione walk-forward OOS del Modulo 1. Prima si chiamava WalkForwardConfig e collideva con l'omonima classe — diversa — del Modulo 3; il vecchio nome resta come alias in event_discovery.models, ma è preferibile quello esplicito.

from forgedge import DiscoveryConfig
from forgedge.event_discovery.models import EventWalkForwardConfig, GateParams

config = DiscoveryConfig(
    train_ratio=0.80,
    walk_forward=EventWalkForwardConfig(
        n_splits=4,
        min_pass_rate=0.75,   # più severo: 3 su 4 finestre devono passare
    ),
)

DiscoveryConfig

Configurazione principale del Modulo 1. Controlla gate, composizione degli eventi AND, split IS/OOS e walk-forward.

from forgedge import EventDiscovery, DiscoveryConfig
from forgedge.event_discovery.models import GateParams, EventWalkForwardConfig

ed = EventDiscovery(
    enriched,
    config=DiscoveryConfig(
        train_ratio=0.80,
        max_and_components=2,                   # composizione single-pass legacy (vedi sotto)
        gate_params=GateParams(min_tpm=0.5, dispersion_margin=1.3, min_episodes=10),
        walk_forward=EventWalkForwardConfig(n_splits=4, min_pass_rate=0.75),
        scale_free_overrides={"rsi_14": True},  # forza scale-free su RSI
        diversity_gate_enabled=True,            # deduplicazione Jaccard opt-in
        diversity_threshold=0.85,
        retain_raw_events=True,                 # es. per TargetOptimizer, che ha bisogno di .raw_events
    ),
)
candidates = ed.run()

Parametri di composizione di forge() (issue #254 Fase 8)

Non sono campi di DiscoveryConfig — parametri a livello orchestratore su forge() stesso che decidono dove avviene la composizione AND:

GradePairingConfig (forgedge.composition)

Letto solo quando two_pass_composition=True.

from forgedge import forge, DiscoveryConfig
from forgedge.composition import GradePairingConfig

result = forge(
    kpi,
    timeframe="1D",
    event_discovery_config=DiscoveryConfig(max_and_components=1),  # richiesto
    two_pass_composition=True,          # il default — esplicito qui per chiarezza
    grade_pairing_config=GradePairingConfig(max_components=3, per_stratum_pair_cap=150),
)
result.grading_candidates   # pool 1D pre-composizione della passata 1
result.candidates            # output pooled della passata 2 — ciò su cui M3 ha realmente operato

Modulo 2

PromotionThresholds

Soglie statistiche IS che contribuiscono al grade A–D. Non bloccano la promozione (eccetto casi estremi): informano il grade. Viene passato come campo thresholds di AlphaConfig.

min_activations/min_oos_activations non esistono più su questa dataclass — il controllo sulla numerosità del campione IS/OOS è ora una costante di modulo hardcoded, _MIN_STATS_CASES = 10, in alpha_discovery/discovery.py (una diagnostica non bloccante, non un campo configurabile). Costruire PromotionThresholds con uno di questi nomi solleva oggi un TypeError.

from forgedge import AlphaConfig, PromotionThresholds

config = AlphaConfig(
    asset="BTC",
    timeframe="1H",
    thresholds=PromotionThresholds(
        ic_min_abs=0.03,
        min_lift=0.10,
        min_cohens_d=0.20,
        oos_max_p=0.05,
    ),
)

AlphaConfig

Configurazione principale del Modulo 2. Controlla la grid degli orizzonti, la derivazione del target, la suddivisione IS/OOS e i metadati di tracciabilità.

TargetConfig

Target economico specificato dall'utente per AlphaConfig.fixed_target e il workflow TargetOptimizer.

from forgedge import AlphaDiscovery, AlphaConfig, PromotionThresholds

ad = AlphaDiscovery(
    ed.df,
    candidates,
    AlphaConfig(
        asset="ADAUSDC",
        timeframe="4H",
        horizon_grid=(4, 8, 12, 24, 48, 72, 96),   # orizzonti in barre 4H
        train_ratio=0.75,
        fee_per_side=0.001,
        thresholds=PromotionThresholds(
            min_lift=0.08,
            min_cohens_d=0.15,
            oos_max_p=0.10,
        ),
    ),
)
contracts = ad.run()

Modulo 3

BacktestParams

Parametri dell'esecuzione di un singolo backtest: direzione, tipo di ordine, livelli di ingresso/uscita e fee. Raramente usato direttamente dall'utente — la grid viene costruita da GridSpec e RuleDiscovery deriva direction, sell_pct e target_h di partenza dall'AlphaContract.

ScoringParams

Soglie usate dalla funzione di scoring della grid per combinare il Profit Factor con la regolarità degli arrivi dei trade. pf_score_tpm = profit_factor × c_norm, dove c_norm è l'inverso dell'indice di dispersione (μ/σ², troncato a 1): è scale-free, quindi una regola non viene penalizzata perché opera più spesso, ma solo perché opera a raffiche. "Abbastanza trade" è una domanda separata, presidiata da criteria.min_tpm e dal floor dinamico qui sotto.

Entrambi i campi sono risolti a livello di sessione: lasciandoli non impostati li riempie resolve(), e config_report() mostra il valore che verrà eseguito.

GridSpec

Definisce lo spazio di ricerca della grid search dei parametri operativi. I campi lasciati a None usano la grid di default predefinita da RuleDiscovery.

from forgedge.rule_discovery.models import GridSpec

grid = GridSpec(
    buy_drop_pct=[0.005, 0.010, 0.015],
    sell_pct=[0.030, 0.040, 0.050, 0.060],
    target_h=[12, 24, 36],
    buy_delay_bar=[3, 6],
)

RuleWalkForwardConfig (Modulo 3)

Configura la validazione walk-forward OOS del Modulo 3. Prima si chiamava WalkForwardConfig; il vecchio nome resta come alias, sia in rule_discovery.models sia al livello superiore (forgedge.WalkForwardConfig ha sempre risolto a questa classe).

SelectionCriteria

Gate di promozione del Modulo 3. Definisce le condizioni per i verdetti EDGE, PARTIAL-EDGE e NON-EDGE.

Quattro di questi campi sono preset-parametrizzati (#207) invece di default universali fissi — forge_preset() li imposta per profilo perché le descrizioni dei preset stessi divergono esplicitamente su precisione-vs-volume:

max_zero_months_edge/max_zero_months_partial non esistono più su questa dataclass — sostituiti dal campo basato su tasso min_active_month_rate sopra. Costruire SelectionCriteria con uno di questi nomi solleva oggi un TypeError.

from forgedge import RuleDiscovery, RuleDiscoveryConfig, SelectionCriteria

config = RuleDiscoveryConfig(
    criteria=SelectionCriteria(
        min_profit_factor=1.8,   # meno severo per asset ad alta volatilità
        min_win_rate=0.50,
        early_elimination=False, # diagnostica completa anche su NON-EDGE
    ),
)
rd = RuleDiscovery(ed.df, contract, cand, config=config)

RuleDiscoveryConfig

Configurazione principale del Modulo 3. Aggrega tutti i sotto-configuratori: parametri base del backtest, scoring, grid di ricerca, walk-forward e criteri di selezione.

from forgedge import (
    RuleDiscovery, RuleDiscoveryConfig, BacktestParams,
    SelectionCriteria, RuleWalkForwardConfig,
)
from forgedge.rule_discovery.models import GridSpec, ScoringParams

config = RuleDiscoveryConfig(
    base_params=BacktestParams(fee=0.001),
    grid=GridSpec(
        buy_drop_pct=[0.005, 0.010, 0.015, 0.020],
        sell_pct=[0.030, 0.040, 0.050, 0.060],
        target_h=[12, 24, 36, 48],
        buy_delay_bar=[3, 6],
    ),
    walk_forward=RuleWalkForwardConfig(n_splits=5, min_train_months=8),
    criteria=SelectionCriteria(min_profit_factor=2.0, min_win_rate=0.55),
)
rd = RuleDiscovery(ed.df, contract, cand, config=config)
resp = rd.run()

Modulo 4

RegistryConfig

Configurazione del Modulo 4. Controlla deduplicazione, classificazione genericity e opzioni di export.

from forgedge import RuleRegistry, RegistryConfig

config = RegistryConfig(
    overlap_threshold=0.65,         # deduplication più aggressiva
    cross_pf_threshold=1.8,         # alza il floor assoluto per asset illiquidi
    min_cross_pf_retention=0.7,     # e tollera un po' più di decadimento fuori casa
    generic_ratio_threshold=0.5,    # GENERIC se ≥ 50% ticker PASS
    export_format="csv",
    html_charts=True,
    export_duplicates=False,        # escludi i duplicati dall'export
)
registry = RuleRegistry.from_forge_results(results, config=config).run()

Preset — forge_preset()

I default documentati sopra (GateParams, SelectionCriteria, e diversi campi di AlphaConfig/PromotionThresholds) vengono regolarmente sovrascritti in blocco da quattro preset nominati, scelti per profilo di ricerca, non per asset:

from forgedge import forge, forge_preset

disc_cfg, alpha_cfg, rd_cfg = forge_preset("balanced", timeframe="1D", asset="BTC")
result = forge(kpi, event_discovery_config=disc_cfg, alpha_config=alpha_cfg,
                rule_discovery_config=rd_cfg)

forge_preset(preset, timeframe, asset="ASSET", train_ratio=0.70, **overrides) imposta i criteri di frequenza di M1/M2/M3 (e diversi campi dipendenti) in modo coerente per il timeframe scelto, e restituisce la tripla pronta all'uso (DiscoveryConfig, AlphaConfig, RuleDiscoveryConfig). Ogni parametro che calcola può essere sovrascritto per nome via **overrides:

forgedge.presets.preset_info() stampa i parametri numerici risolti per uno o tutti i preset, utile per verificare a cosa risolve davvero un preset su un dato timeframe prima di lanciarlo. Vedi la lista dei pitfall della skill forgedge per due insidie reali e timeframe-specifiche: i preset su "1D" possono far scattare oos_span_too_short in config_report() su una storia modesta (il controllo che fa il suo lavoro, non un preset rotto), e "sniper" non va combinato con il rotation calibrator.

Riepilogo delle importazioni

Nota: le due config walk-forward hanno ora nomi espliciti — EventWalkForwardConfig (Modulo 1) e RuleWalkForwardConfig (Modulo 3), entrambe importabili da forgedge. L'alias WalkForwardConfig continua a funzionare: al livello superiore risolve alla classe del Modulo 3, dentro event_discovery.models / rule_discovery.models a quella del modulo corrispondente.

Risoluzione dei parametri — UNSET e il resolver

I campi di configurazione hanno tre stati, non due:

UNSET esiste perché un default normale non può rispondere alla domanda che un resolver deve porsi: AlphaConfig.timestamp_col == "open_dt" è identico sia che l'utente l'abbia scritto sia che l'abbia ereditato.

from forgedge import UNSET, PipelineContext, collect_context, resolve

bundle = {"event_discovery": disc, "alpha": alpha, "rule_discovery": rd}
ctx = collect_context(bundle, PipelineContext.from_frame(kpi, timeframe="1D"))
resolved, trace, violations = resolve(bundle, ctx)
print(trace.to_text())

resolve() restituisce copie — ispezionare una configurazione non è mai un effetto collaterale su di essa — ed è idempotente. forge() lo fa una volta all'avvio ed espone il risultato su ForgeResult.context / .resolution / .coherence.

La derivazione legge il timeframe, lo schema e i valori delle config; non legge mai i dati (n_bars, span_months), visibili solo alla metà check. Questo rende resolve() totale senza il frame — ed è ciò che permette a un'ispezione di mostrare esattamente quello che girerà — e toglie la tentazione di limitare un requisito alla storia disponibile invece di segnalare che non ci sta.

Precedenza, dalla più forte: un PipelineContext esplicito → argomenti di forge() → campi impostati in una qualsiasi config → default di classe. Due config in disaccordo sullo stesso valore vengono segnalate, mai riconciliate in silenzio.