exp_1106

FORMULA_NAME = "Recovery Quality Regime Momentum Handoff (v1106)"
LOGIC_VARIANT_COUNT = 3
NOTES = """mode=explore; family=recovery-quality-regime-momentum-hybrid
New hybrid family built by combining the recovery-quality champion's repaired-rebound architecture with the regime-momentum-quality-value family's explicit bull-vs-defense arbitration, but turning them into a three-stage handoff instead of a flat blend: leadership branch rewards already-confirmed winners, repair branch promotes mid-stage recoveries only when durability agrees, and defense branch keeps low-vol profitable survivors in charge unless a rebound is unusually well-supported. The conflict resolver is explicit: rebound without quality is capped in repair/defense, while strong quality plus trend can outrank a deeper drawdown even if the raw rebound sleeve looks tempting.
Deliberate metric coverage this run: actively use one momentum cluster (return_1m_pct, return_3m_pct, return_6m_pct, momentum_12_1_pct), one trend/recovery cluster (from_200d_ma_pct plus from_52w_high_pct), one volatility check, two liquidity checks, one income check, one valuation check, one growth cluster, one quality cluster, and one size tilt via direct market-cap thresholds. Deliberate weight-0 metrics this run are return_12m_pct, avg_daily_volume_3m, dividend_ttm, forward_pe, peg, operating_income_growth_pct, free_cash_flow_growth_pct, forward_eps, shares_outstanding, close, adj_close, high_52w, ma_200d, eps_ttm, revenue_ttm, operating_income_ttm, and free_cash_flow_ttm so the backtest can test a different information mix from the recent recovery-quality degradations without silently forgetting the full menu."""

RECOVERY_SLEEVE = {
    "from_200d_ma_pct": (0.34, +1),
    "from_52w_high_pct": (0.28, +1),
    "return_3m_pct": (0.24, +1),
    "return_1m_pct": (0.14, +1),
}

QUALITY_SLEEVE = {
    "operating_margin_pct": (0.22, +1),
    "free_cash_flow_margin_pct": (0.24, +1),
    "revenue_growth_pct": (0.18, +1),
    "eps_growth_pct": (0.14, +1),
    "trading_days_3m": (0.10, +1),
    "avg_daily_dollar_volume_3m": (0.12, +1),
}

MOMENTUM_SLEEVE = {
    "momentum_12_1_pct": (0.36, +1),
    "return_6m_pct": (0.30, +1),
    "from_200d_ma_pct": (0.20, +1),
    "realized_vol_3m": (0.14, -1),
}

DEFENSE_SLEEVE = {
    "realized_vol_3m": (0.28, -1),
    "from_200d_ma_pct": (0.16, +1),
    "operating_margin_pct": (0.18, +1),
    "free_cash_flow_margin_pct": (0.20, +1),
    "trading_days_3m": (0.08, +1),
    "avg_daily_dollar_volume_3m": (0.10, +1),
}


def _coverage_weighted_score(symbol, zmaps, weights):
    total = 0.0
    seen = 0.0
    for metric, (weight, sign) in weights.items():
        z = zmaps[metric].get(symbol)
        if z is not None:
            total += weight * sign * z
            seen += weight
    if seen <= 0.0:
        return 0.0
    return total / seen


def _avg_present(*values):
    total = 0.0
    count = 0
    for value in values:
        if value is not None:
            total += value
            count += 1
    if count == 0:
        return None
    return total / count


def _branch(regime):
    breadth = regime.get("breadth", 0.0) or 0.0
    med_trend = regime.get("median_from_200d_ma_pct", 0.0) or 0.0
    med_mom = regime.get("median_momentum_12_1_pct", 0.0) or 0.0
    avg_vol = regime.get("avg_realized_vol_3m", 0.0) or 0.0

    if regime.get("bull") and breadth >= 0.60 and med_trend >= 3.0 and med_mom >= 4.0:
        return "leadership"
    if breadth <= 0.46 or med_trend <= -2.0 or avg_vol >= 31.0:
        return "defense"
    return "repair"


def score_universe(stocks, regime, ctx):
    metrics = {}
    for book in (RECOVERY_SLEEVE, QUALITY_SLEEVE, MOMENTUM_SLEEVE, DEFENSE_SLEEVE):
        for metric in book:
            metrics[metric] = True

    zmaps = {}
    for metric in metrics:
        zmaps[metric] = ctx.z(metric)

    branch = _branch(regime)
    scores = {}

    for row in stocks:
        sym = row["symbol"]

        recovery = _coverage_weighted_score(sym, zmaps, RECOVERY_SLEEVE)
        quality = _coverage_weighted_score(sym, zmaps, QUALITY_SLEEVE)
        momentum = _coverage_weighted_score(sym, zmaps, MOMENTUM_SLEEVE)
        defense = _coverage_weighted_score(sym, zmaps, DEFENSE_SLEEVE)

        trend = row.get("from_200d_ma_pct")
        drawdown = row.get("from_52w_high_pct")
        ret1 = row.get("return_1m_pct")
        ret3 = row.get("return_3m_pct")
        ret6 = row.get("return_6m_pct")
        mom = row.get("momentum_12_1_pct")
        vol = row.get("realized_vol_3m")
        trading_days = row.get("trading_days_3m")
        dollar_vol = row.get("avg_daily_dollar_volume_3m")
        div_yield = row.get("dividend_yield_ttm_pct")
        pe = row.get("pe")
        rev_growth = row.get("revenue_growth_pct")
        eps_growth = row.get("eps_growth_pct")
        op_margin = row.get("operating_margin_pct")
        fcf_margin = row.get("free_cash_flow_margin_pct")
        market_cap = row.get("market_cap")

        durability_gate = _avg_present(op_margin, fcf_margin, rev_growth, eps_growth)
        repair_gate = _avg_present(trend, drawdown, ret3, ret1)

        if branch == "leadership":
            total = 0.44 * momentum + 0.28 * quality + 0.18 * recovery + 0.10 * defense

            if trend is not None:
                if trend > 10:
                    total += 0.26
                elif trend > 4:
                    total += 0.14
                elif trend < 0:
                    total -= 0.55

            if drawdown is not None:
                if drawdown > -10:
                    total += 0.24
                elif drawdown > -20:
                    total += 0.10
                elif drawdown < -35:
                    total -= 0.34

            if mom is not None:
                if mom >= 8 and mom <= 30:
                    total += 0.22
                elif mom > 30:
                    total += 0.08
                elif mom < -6:
                    total -= 0.28

            if ret6 is not None:
                if ret6 >= 10 and ret6 <= 34:
                    total += 0.18
                elif ret6 < -6:
                    total -= 0.24

            if vol is not None:
                if vol < 24:
                    total += 0.10
                elif vol > 42:
                    total -= 0.20

            if pe is not None:
                if pe > 0 and pe < 28:
                    total += 0.12
                elif pe > 45:
                    total -= 0.18

            if div_yield is not None and div_yield >= 0.8 and div_yield <= 4.5:
                total += 0.05

            if market_cap is not None:
                if market_cap < 9000000000:
                    total += 0.07
                elif market_cap > 250000000000:
                    total -= 0.06

            if recovery > 0.35 and quality < -0.05:
                total -= 0.24
            elif momentum > 0.25 and quality > 0.10 and trend is not None and trend > 6:
                total += 0.14

        elif branch == "repair":
            total = 0.39 * recovery + 0.31 * quality + 0.18 * momentum + 0.12 * defense

            if drawdown is not None:
                if drawdown < -55:
                    total -= 0.82
                elif drawdown < -38:
                    total -= 0.24
                elif drawdown >= -32 and drawdown <= -10:
                    total += 0.30
                elif drawdown > -6:
                    total -= 0.08

            if trend is not None:
                if trend > 2 and trend <= 14:
                    total += 0.24
                elif trend < -8:
                    total -= 0.44

            if ret3 is not None:
                if ret3 >= 4 and ret3 <= 22:
                    total += 0.18
                elif ret3 > 30:
                    total -= 0.08
                elif ret3 < -8:
                    total -= 0.20

            if ret1 is not None:
                if ret1 >= 1 and ret1 <= 10:
                    total += 0.10
                elif ret1 > 16:
                    total -= 0.08
                elif ret1 < -10:
                    total -= 0.12

            if durability_gate is not None:
                if durability_gate > 12:
                    total += 0.14
                elif durability_gate < 1:
                    total -= 0.18

            if pe is not None:
                if pe > 0 and pe < 22:
                    total += 0.10
                elif pe > 40:
                    total -= 0.16

            if div_yield is not None and div_yield > 0.5:
                total += 0.05

            if trading_days is not None:
                if trading_days >= 61:
                    total += 0.08
                elif trading_days < 56:
                    total -= 0.12

            if dollar_vol is not None and dollar_vol < 2500000:
                total -= 0.10

            if market_cap is not None:
                if market_cap < 20000000000:
                    total += 0.08
                elif market_cap > 200000000000:
                    total -= 0.08

            if recovery > 0.18 and quality > 0.08:
                total += 0.18
            elif recovery > 0.20 and quality < -0.10:
                total -= 0.32

            if momentum > 0.30 and recovery < 0.00 and quality < 0.00:
                total -= 0.16

        else:
            total = 0.43 * defense + 0.29 * quality + 0.16 * momentum + 0.12 * recovery

            if vol is not None:
                if vol < 22:
                    total += 0.24
                elif vol > 40:
                    total -= 0.34

            if trend is not None:
                if trend > 1:
                    total += 0.18
                elif trend < -6:
                    total -= 0.48

            if drawdown is not None:
                if drawdown > -18:
                    total += 0.10
                elif drawdown < -40:
                    total -= 0.30

            if trading_days is not None:
                if trading_days >= 62:
                    total += 0.10
                elif trading_days < 57:
                    total -= 0.14

            if div_yield is not None:
                if div_yield >= 1.2 and div_yield <= 5.5:
                    total += 0.10
                elif div_yield == 0:
                    total -= 0.04

            if pe is not None:
                if pe > 0 and pe < 20:
                    total += 0.12
                elif pe > 35:
                    total -= 0.18

            if durability_gate is not None:
                if durability_gate > 10:
                    total += 0.12
                elif durability_gate < 0:
                    total -= 0.18

            if market_cap is not None and market_cap > 12000000000:
                total += 0.05

            if recovery > 0.20 and defense < 0.00:
                total -= 0.26
            elif defense > 0.12 and quality > 0.08 and trend is not None and trend > 0:
                total += 0.12

        if repair_gate is not None and repair_gate < -8:
            total -= 0.12

        scores[sym] = total

    return scores