FORGE — Complete Configuration Reference

All configuration objects in FORGE are Python dataclasses. They ship with sensible defaults calibrated for crypto 1H data and can be instantiated with no arguments for typical use cases. Fields are mutable after construction: you only need to set the fields you want to change from their defaults. Every configuration object is passed explicitly to its corresponding pipeline component; there are no global singletons or environment-level settings.

Module 0 — Market Context

EMAProxyConfig

Configures the EMA-proxy classifier: data source, automatic window derivation, regime thresholds, and adaptive calibration.

from forgedge import MarketContext, MarketContextConfig, EMAProxyConfig

enriched = MarketContext(
    kpi,
    config=MarketContextConfig(
        stable_window=12,
        ema_proxy=EMAProxyConfig(
            auto_window=True,
            window_unit="day",
            bar_hours=4.0,              # 4H bars
            threshold_mode="balanced",
            target_distribution=[0.10, 0.20, 0.40, 0.20, 0.10],
            threshold_basis="expanding",  # causal, no look-ahead
        ),
    ),
).run()

MarketContextConfig

Top-level configuration container for Module 0.

from forgedge import MarketContext, MarketContextConfig, EMAProxyConfig

enriched = MarketContext(
    kpi,
    config=MarketContextConfig(
        stable_window=6,          # more reactive to regime changes
        ema_proxy=EMAProxyConfig(
            auto_window=True,
            window_unit="day",
            bar_hours=1.0,
        ),
    ),
).run()

Module 1 — Event Discovery

GateParams

Thresholds for the ConsistencyGate — the structural filter that verifies whether an event has stable temporal structure.

Since issue #134, the gate operates in one of two counting modes, selected by event_counting: "episode" (the default) counts maximal runs of consecutive activations rather than raw bars, so a persistent multi-bar state (a 3–5 bar RSI < 30 stretch) is not wrongly penalised as if it were several independent triggers; "bar" reproduces the pre-#134 counting exactly, bar by bar. The two modes are identical for impulse events (crossovers, candlestick patterns — one bar per episode).

The dual mode changes which dispersion field the gate actually reads (issue #205): max_dispersion is the raw Index-of-Dispersion threshold, but it is read only in "bar" mode. In "episode" mode the gate instead compares against poisson_floor(n_months) × dispersion_margin — a margin over the statistically-defensible Poisson floor, not an absolute ID — because the floor almost always dominated a fixed max_dispersion in practice (measured: 12 of 16 preset×timeframe combinations never had max_dispersion bind). So on the default event_counting="episode", tune dispersion_margin, not max_dispersion.

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

config = DiscoveryConfig(
    gate_params=GateParams(
        min_tpm=0.3,             # less strict for shorter datasets
        dispersion_margin=1.6,   # more slack above the Poisson floor
        min_episodes=5,
        event_counting="episode",  # default; "bar" reproduces pre-#134 behaviour
    )
)

# Opt-in: reject events firing too often, not just too rarely
ranged_config = DiscoveryConfig(
    gate_params=GateParams(tpm_mode="ranged", min_tpm=4.0, tpm_tolerance=2.0)  # band = [2.0, 6.0]
)

The fields above replaced an older GateParams(min_act, min_months, max_conc, min_tpm) schema; none of min_act/min_months/max_conc exist any more, and constructing GateParams with them raises TypeError today. Several of this repo's own examples/*.py scripts still use the old schema — see the forgedge skill's pitfall list before copying from them.

EventWalkForwardConfig (Module 1)

Configures Module 1 walk-forward OOS validation. Formerly named WalkForwardConfig, which collided with Module 3's distinct class of the same name; the old name still works as an alias in event_discovery.models, but prefer the explicit one.

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,   # stricter: 3 of 4 windows must pass
    ),
)

DiscoveryConfig

Main configuration for Module 1. Controls gate thresholds, AND composition, IS/OOS split, and 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,                   # legacy single-pass composition (see below)
        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},  # force scale-free on RSI
        diversity_gate_enabled=True,            # opt-in Jaccard deduplication
        diversity_threshold=0.85,
        retain_raw_events=True,                 # e.g. for TargetOptimizer, which needs .raw_events
    ),
)
candidates = ed.run()

forge() composition parameters (issue #254 Phase 8)

Not DiscoveryConfig fields — orchestrator-level parameters on forge() itself that decide where AND composition happens:

GradePairingConfig (forgedge.composition)

Read only when 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),  # required
    two_pass_composition=True,          # the default — explicit here for clarity
    grade_pairing_config=GradePairingConfig(max_components=3, per_stratum_pair_cap=150),
)
result.grading_candidates   # pass-1, pre-composition 1D pool
result.candidates            # pass-2 pooled output — what M3 actually operated on

Module 2 — Alpha Discovery

PromotionThresholds

IS statistical thresholds that contribute to the A–D grade. They do not block promotion (except in extreme cases) — they inform the grade.

min_activations/min_oos_activations do not exist on this dataclass any more — the IS/OOS sample-size check is now a hardcoded module constant, _MIN_STATS_CASES = 10, in alpha_discovery/discovery.py (a non-blocking diagnostic, not a configurable field). Constructing PromotionThresholds with either name raises TypeError today.

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

Main configuration for Module 2. Controls the horizon grid, target derivation, IS/OOS split, and traceability metadata.

TargetConfig

User-specified economic target for AlphaConfig.fixed_target and the TargetOptimizer workflow.

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),   # horizons in 4H bars
        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()

Module 3 — Rule Discovery

BacktestParams

Execution parameters for a single backtest run: direction, order type, entry/exit levels, and fee.

BacktestParams is rarely used directly. The grid is defined via GridSpec; RuleDiscovery derives direction, sell_pct, and target_h from the AlphaContract.

ScoringParams

Thresholds used by the grid scoring function to combine Profit Factor with the regularity of the trade arrivals. pf_score_tpm = profit_factor × c_norm, where c_norm is the inverse index of dispersion (μ/σ², capped at 1) — scale-free, so a rule is not penalised for trading more often, only for trading in bursts. "Enough trades" is a separate question, enforced by criteria.min_tpm and the dynamic trade floor below.

Both fields are session-resolved: leave them unset and resolve() fills them in, config_report() shows the value that will run.

GridSpec

Defines the parameter search space for the Rule Discovery grid search.

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 (Module 3)

Configures Module 3 walk-forward OOS validation. Formerly named WalkForwardConfig; the old name still works as an alias, both in rule_discovery.models and at the top level (forgedge.WalkForwardConfig has always resolved to this one).

SelectionCriteria

Module 3 promotion gates. Defines the conditions for EDGE, PARTIAL-EDGE, and NON-EDGE verdicts.

Four of these fields are preset-parametrized (#207) rather than flat universal defaults — forge_preset() sets them per profile because the presets' own descriptions explicitly diverge on precision-vs-volume:

max_zero_months_edge/max_zero_months_partial do not exist on this dataclass any more — replaced by the rate-based min_active_month_rate above. Constructing SelectionCriteria with either name raises TypeError today.

from forgedge import RuleDiscovery, RuleDiscoveryConfig, SelectionCriteria

config = RuleDiscoveryConfig(
    criteria=SelectionCriteria(
        min_profit_factor=1.8,   # less strict for high-volatility assets
        min_win_rate=0.50,
        early_elimination=False, # full diagnostics even on NON-EDGE
    ),
)
rd = RuleDiscovery(ed.df, contract, cand, config=config)

RuleDiscoveryConfig

Main configuration for Module 3. Aggregates all sub-configurators.

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()

Module 4 — Rule Registry

RegistryConfig

Module 4 configuration. Controls deduplication, genericity classification, and export.

generic_ratio_threshold = 2/3 — the value is exactly 2/3 (not 0.67). On 3 external tickers: 2 PASS → GENERIC, 1 PASS → PARTIAL.

from forgedge import RuleRegistry, RegistryConfig

config = RegistryConfig(
    overlap_threshold=0.65,         # more aggressive deduplication
    cross_pf_threshold=1.8,         # raise the absolute floor for illiquid assets
    min_cross_pf_retention=0.7,     # and tolerate a little more decay away from home
    generic_ratio_threshold=0.5,    # GENERIC if ≥ 50% of tickers PASS
    export_format="csv",
    html_charts=True,
    export_duplicates=False,         # exclude duplicates from export
)
registry = RuleRegistry.from_forge_results(results, config=config).run()

Presets — forge_preset()

The defaults documented above (GateParams, SelectionCriteria, and several AlphaConfig/PromotionThresholds fields) are routinely overridden as a group by four named presets, chosen by search profile, not by 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) sets M1/M2/M3's frequency criteria (and several dependent fields) consistently for the chosen timeframe, and returns the ready-to-use (DiscoveryConfig, AlphaConfig, RuleDiscoveryConfig) triple. Any of the parameters it computes can be overridden by name via **overrides:

forgedge.presets.preset_info() prints the resolved numeric parameters for any (or all) presets, useful for checking what a preset actually resolves to on a given timeframe before running it. See the forgedge skill's pitfall list for two real, timeframe-specific gotchas: "1D" presets can raise config_report()'s oos_span_too_short on a modest history (the checker doing its job, not a broken preset), and "sniper" should not be combined with the rotation calibrator.

Parameter resolution — UNSET and the resolver

Configuration fields fall into three states rather than two:

UNSET exists because a plain default cannot answer the question a resolver has to ask: AlphaConfig.timestamp_col == "open_dt" looks identical whether the caller wrote it or inherited it.

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() returns copies — inspecting a configuration is never a side effect on it — and is idempotent. forge() does this once at start-up and exposes the result on ForgeResult.context / .resolution / .coherence.

Derivation reads the timeframe, the schema and the configs' own values; it never reads the data (n_bars, span_months), which are visible to the check half only. That keeps resolve() total without the frame — which is what lets an inspection show exactly what will run — and it removes the temptation to cap a requirement to fit the available history instead of reporting that it does not fit.

Precedence, strongest first: an explicit PipelineContext → forge()'s own arguments → fields set in any config → the class default. Two configs that disagree on the same value are reported, never silently reconciled.

Import summary

The two walk-forward configs are now explicitly named: EventWalkForwardConfig (Module 1) and RuleWalkForwardConfig (Module 3), both importable from forgedge. The legacy WalkForwardConfig alias still resolves — to the Module 3 class at the top level, and to each module's own class inside event_discovery.models / rule_discovery.models.