exp_1191

FORMULA_NAME = "Contrarian 52-Week Recovery Quality Regime Momentum Hybrid (Arbitrated Repair Relay, v1191)"
LOGIC_VARIANT_COUNT = 4
NOTES = """mode=explore; family=contrarian-52w-recovery-quality-regime-momentum-hybrid
This variant combines four orthogonal ideas into an explicit arbitration system rather than a static blend: deep-52-week contrarian repair, early recovery confirmation, durable quality support, and trend momentum continuation. The structure is intentionally distinct from the parent relay because the regime branch does not merely reweight sleeves; it changes which conflicts are permitted. In panic and stressed tapes, broken names only score if they show concrete repair plus internal quality support. In neutral tapes, repaired recoveries can outrank pure momentum when extension is limited and durability is better. In risk-on tapes, momentum can dominate, but only if overextension, volatility, and low-quality internals do not trigger crowding taxes. The arbitration is explicit: each stock receives sleeve scores for repair, momentum, and durability, then branch-specific gates decide whether to reward convergence, suppress contradiction, or route capital to the strongest justified sleeve.
Deliberate metric coverage this run: momentum uses return_1m_pct, return_3m_pct, return_6m_pct, return_12m_pct, and momentum_12_1_pct; trend/recovery uses from_200d_ma_pct and from_52w_high_pct; volatility uses realized_vol_3m; liquidity uses avg_daily_volume_3m, avg_daily_dollar_volume_3m, and trading_days_3m; income uses dividend_yield_ttm_pct and dividend_ttm as secondary ballast; valuation uses pe, forward_pe, and peg; growth uses eps_growth_pct, revenue_growth_pct, operating_income_growth_pct, free_cash_flow_growth_pct, and forward_eps; quality uses operating_margin_pct and free_cash_flow_margin_pct; size uses market_cap as a crowding/fragility tilt rather than a direct preference.
Deliberate weight-0 metrics this run: shares_outstanding, close, adj_close, high_52w, ma_200d, eps_ttm, revenue_ttm, operating_income_ttm, and free_cash_flow_ttm. Correlated momentum features are separated by sleeve role, valuation is only active where quality/growth can justify it, and sparse fundamentals are normalized by present weight so missing fields do not automatically dominate or disqualify a stock.
"""

ACTIVE_METRICS = (
    "return_1m_pct",
    "return_3m_pct",
    "return_6m_pct",
    "return_12m_pct",
    "momentum_12_1_pct",
    "from_200d_ma_pct",
    "from_52w_high_pct",
    "realized_vol_3m",
    "avg_daily_volume_3m",
    "avg_daily_dollar_volume_3m",
    "trading_days_3m",
    "dividend_yield_ttm_pct",
    "dividend_ttm",
    "pe",
    "forward_pe",
    "peg",
    "eps_growth_pct",
    "revenue_growth_pct",
    "operating_income_growth_pct",
    "free_cash_flow_growth_pct",
    "forward_eps",
    "operating_margin_pct",
    "free_cash_flow_margin_pct",
    "market_cap",
)

REPAIR = {
    "from_52w_high_pct": (0.26, -1),
    "from_200d_ma_pct": (0.16, -1),
    "return_1m_pct": (0.10, +1),
    "return_3m_pct": (0.10, +1),
    "realized_vol_3m": (0.08, -1),
    "avg_daily_dollar_volume_3m": (0.06, +1),
    "trading_days_3m": (0.04, +1),
    "operating_margin_pct": (0.07, +1),
    "free_cash_flow_margin_pct": (0.07, +1),
    "free_cash_flow_growth_pct": (0.06, +1),
}

RECOVERY = {
    "from_52w_high_pct": (0.18, -1),
    "from_200d_ma_pct": (0.18, +1),
    "return_3m_pct": (0.13, +1),
    "return_6m_pct": (0.08, +1),
    "momentum_12_1_pct": (0.08, +1),
    "realized_vol_3m": (0.07, -1),
    "avg_daily_volume_3m": (0.05, +1),
    "peg": (0.05, -1),
    "operating_income_growth_pct": (0.08, +1),
    "operating_margin_pct": (0.10, +1),
}

MOMENTUM = {
    "momentum_12_1_pct": (0.18, +1),
    "return_6m_pct": (0.16, +1),
    "return_12m_pct": (0.10, +1),
    "return_3m_pct": (0.09, +1),
    "from_200d_ma_pct": (0.09, +1),
    "from_52w_high_pct": (0.08, +1),
    "realized_vol_3m": (0.08, -1),
    "avg_daily_dollar_volume_3m": (0.06, +1),
    "eps_growth_pct": (0.06, +1),
    "forward_pe": (0.05, -1),
    "free_cash_flow_margin_pct": (0.05, +1),
}

DURABILITY = {
    "operating_margin_pct": (0.16, +1),
    "free_cash_flow_margin_pct": (0.16, +1),
    "operating_income_growth_pct": (0.11, +1),
    "free_cash_flow_growth_pct": (0.11, +1),
    "revenue_growth_pct": (0.07, +1),
    "eps_growth_pct": (0.06, +1),
    "peg": (0.06, -1),
    "pe": (0.05, -1),
    "dividend_yield_ttm_pct": (0.04, +1),
    "dividend_ttm": (0.03, +1),
    "trading_days_3m": (0.05, +1),
    "realized_vol_3m": (0.10, -1),
}

BRANCHES = ("panic_repair", "stressed_recovery", "balanced_relay", "risk_on_momentum")


def _to_float(value):
    if value is None:
        return None
    if isinstance(value, bool):
        return 1.0 if value else 0.0
    if isinstance(value, (int, float)):
        return float(value)
    return None


def _metric_ranks(stocks, metric):
    pairs = []
    for stock in stocks:
        val = _to_float(stock.get(metric))
        if val is not None:
            pairs.append((val, stock.get("symbol")))
    if not pairs:
        return {}
    pairs.sort(key=lambda x: x[0])
    n = len(pairs)
    if n == 1:
        return {pairs[0][1]: 0.5}
    ranks = {}
    i = 0
    while i < n:
        j = i
        v = pairs[i][0]
        while j + 1 < n and pairs[j + 1][0] == v:
            j += 1
        rank = ((i + j) * 0.5) / (n - 1)
        k = i
        while k <= j:
            ranks[pairs[k][1]] = rank
            k += 1
        i = j + 1
    return ranks


def _build_rank_table(stocks):
    table = {}
    for metric in ACTIVE_METRICS:
        table[metric] = _metric_ranks(stocks, metric)
    return table


def _signed_rank(rank_table, symbol, metric, direction):
    rank = rank_table.get(metric, {}).get(symbol)
    if rank is None:
        return None
    return rank if direction > 0 else (1.0 - rank)


def _weighted_score(rank_table, symbol, weights):
    total = 0.0
    used = 0.0
    for metric, spec in weights.items():
        weight, direction = spec
        val = _signed_rank(rank_table, symbol, metric, direction)
        if val is None:
            continue
        total += weight * val
        used += weight
    if used <= 0.0:
        return 0.0
    return total / used


def _count_present(rank_table, symbol, weights):
    count = 0
    for metric in weights:
        if symbol in rank_table.get(metric, {}):
            count += 1
    return count


def _clamp(x, lo, hi):
    if x < lo:
        return lo
    if x > hi:
        return hi
    return x


def _regime_name(regime):
    if isinstance(regime, str):
        text = regime.lower()
    else:
        text = str(regime).lower() if regime is not None else ""
    if "panic" in text or "crash" in text:
        return "panic_repair"
    if "stress" in text or "bear" in text or "risk_off" in text or "risk-off" in text or "defensive" in text:
        return "stressed_recovery"
    if "bull" in text or "risk_on" in text or "risk-on" in text or "momo" in text or "momentum" in text:
        return "risk_on_momentum"
    return "balanced_relay"


def _branch_from_ctx(ctx):
    if not isinstance(ctx, dict):
        return None
    for key in ("regime", "market_regime", "branch", "state"):
        if key in ctx:
            name = _regime_name(ctx.get(key))
            if name:
                return name
    return None


def _raw(stock, key):
    return _to_float(stock.get(key))


def _repair_evidence(stock, rank_table, symbol):
    r1 = _signed_rank(rank_table, symbol, "return_1m_pct", +1)
    r3 = _signed_rank(rank_table, symbol, "return_3m_pct", +1)
    f200 = _signed_rank(rank_table, symbol, "from_200d_ma_pct", +1)
    high_gap = _signed_rank(rank_table, symbol, "from_52w_high_pct", -1)
    qual = _weighted_score(rank_table, symbol, {
        "operating_margin_pct": (0.5, +1),
        "free_cash_flow_margin_pct": (0.5, +1),
    })
    parts = []
    if r1 is not None:
        parts.append(r1)
    if r3 is not None:
        parts.append(r3)
    if f200 is not None:
        parts.append(f200)
    if high_gap is not None:
        parts.append(high_gap)
    if qual > 0.0:
        parts.append(qual)
    if not parts:
        return 0.0
    return sum(parts) / float(len(parts))


def _extension_risk(stock, rank_table, symbol):
    near_high = _signed_rank(rank_table, symbol, "from_52w_high_pct", +1)
    far_above_200 = _signed_rank(rank_table, symbol, "from_200d_ma_pct", +1)
    hot_1m = _signed_rank(rank_table, symbol, "return_1m_pct", +1)
    vol = _signed_rank(rank_table, symbol, "realized_vol_3m", +1)
    size_small = _signed_rank(rank_table, symbol, "market_cap", -1)
    parts = []
    if near_high is not None:
        parts.append(near_high)
    if far_above_200 is not None:
        parts.append(far_above_200)
    if hot_1m is not None:
        parts.append(hot_1m)
    if vol is not None:
        parts.append(vol)
    if size_small is not None:
        parts.append(size_small)
    if not parts:
        return 0.0
    return sum(parts) / float(len(parts))


def _fragility(stock, rank_table, symbol):
    vol = _signed_rank(rank_table, symbol, "realized_vol_3m", +1)
    liq = _weighted_score(rank_table, symbol, {
        "avg_daily_volume_3m": (0.4, -1),
        "avg_daily_dollar_volume_3m": (0.4, -1),
        "trading_days_3m": (0.2, -1),
    })
    qual = _weighted_score(rank_table, symbol, {
        "operating_margin_pct": (0.5, -1),
        "free_cash_flow_margin_pct": (0.5, -1),
    })
    parts = []
    if vol is not None:
        parts.append(vol)
    if liq > 0.0:
        parts.append(liq)
    if qual > 0.0:
        parts.append(qual)
    if not parts:
        return 0.5
    return sum(parts) / float(len(parts))


def _valuation_support(rank_table, symbol):
    return _weighted_score(rank_table, symbol, {
        "pe": (0.30, -1),
        "forward_pe": (0.30, -1),
        "peg": (0.40, -1),
    })


def score_universe(stocks, regime, ctx):
    rank_table = _build_rank_table(stocks)
    branch = _branch_from_ctx(ctx) or _regime_name(regime)
    scores = {}

    for stock in stocks:
        symbol = stock.get("symbol")
        if not symbol:
            continue

        repair = _weighted_score(rank_table, symbol, REPAIR)
        recovery = _weighted_score(rank_table, symbol, RECOVERY)
        momentum = _weighted_score(rank_table, symbol, MOMENTUM)
        durability = _weighted_score(rank_table, symbol, DURABILITY)

        repair_evidence = _repair_evidence(stock, rank_table, symbol)
        extension = _extension_risk(stock, rank_table, symbol)
        fragility = _fragility(stock, rank_table, symbol)
        value_support = _valuation_support(rank_table, symbol)

        conflict = abs(momentum - repair)
        convergence = 1.0 - conflict if conflict <= 1.0 else 0.0

        has_repair_depth = _signed_rank(rank_table, symbol, "from_52w_high_pct", -1)
        trend_ok = _signed_rank(rank_table, symbol, "from_200d_ma_pct", +1)
        liquid_ok = _weighted_score(rank_table, symbol, {
            "avg_daily_dollar_volume_3m": (0.7, +1),
            "trading_days_3m": (0.3, +1),
        })

        gate_repair = 1.0 if repair_evidence >= 0.52 else 0.70
        if has_repair_depth is not None and has_repair_depth < 0.35:
            gate_repair *= 0.82

        gate_momentum = 1.0 if extension <= 0.72 else 0.72
        if durability < 0.45:
            gate_momentum *= 0.82
        if fragility > 0.68:
            gate_momentum *= 0.82

        gate_durability = 1.0 if durability >= 0.50 else 0.78
        if liquid_ok < 0.35:
            gate_durability *= 0.85

        repair_adj = repair * gate_repair
        momentum_adj = momentum * gate_momentum
        durability_adj = durability * gate_durability
        recovery_adj = recovery * (0.92 + 0.16 * convergence)

        if branch == "panic_repair":
            dominant = repair_adj
            if durability_adj > dominant:
                dominant = durability_adj
            score = (
                0.42 * repair_adj
                + 0.24 * durability_adj
                + 0.18 * recovery_adj
                + 0.08 * value_support
                + 0.08 * convergence
            )
            if repair_adj >= 0.55 and durability_adj >= 0.50:
                score += 0.08
            if momentum_adj > repair_adj + 0.12 and extension > 0.60:
                score -= 0.08
            score -= 0.16 * fragility
            score += 0.10 * dominant

        elif branch == "stressed_recovery":
            dominant = recovery_adj
            if repair_adj > dominant:
                dominant = repair_adj
            score = (
                0.31 * recovery_adj
                + 0.24 * repair_adj
                + 0.23 * durability_adj
                + 0.10 * value_support
                + 0.06 * momentum_adj
                + 0.06 * convergence
            )
            if trend_ok is not None and trend_ok >= 0.52:
                score += 0.05
            if durability_adj >= 0.58 and repair_evidence >= 0.55:
                score += 0.06
            score -= 0.10 * extension
            score -= 0.10 * fragility
            score += 0.08 * dominant

        elif branch == "risk_on_momentum":
            dominant = momentum_adj
            if recovery_adj > dominant and recovery_adj - momentum_adj > 0.10 and extension > 0.75:
                dominant = recovery_adj
            score = (
                0.39 * momentum_adj
                + 0.18 * recovery_adj
                + 0.18 * durability_adj
                + 0.09 * repair_adj
                + 0.08 * value_support
                + 0.08 * convergence
            )
            if momentum_adj >= 0.62 and durability_adj >= 0.48:
                score += 0.07
            if extension > 0.78:
                score -= 0.09
            if fragility > 0.70:
                score -= 0.08
            score += 0.09 * dominant

        else:  # balanced_relay
            dominant = repair_adj
            if momentum_adj > dominant:
                dominant = momentum_adj
            if durability_adj > dominant:
                dominant = durability_adj
            score = (
                0.24 * repair_adj
                + 0.24 * recovery_adj
                + 0.22 * momentum_adj
                + 0.20 * durability_adj
                + 0.05 * value_support
                + 0.05 * convergence
            )
            if repair_adj >= 0.56 and momentum_adj >= 0.56 and durability_adj >= 0.50:
                score += 0.09
            elif dominant == durability_adj and fragility < 0.45:
                score += 0.04
            score -= 0.07 * extension
            score -= 0.06 * fragility
            score += 0.07 * dominant

        present_count = (
            _count_present(rank_table, symbol, REPAIR)
            + _count_present(rank_table, symbol, RECOVERY)
            + _count_present(rank_table, symbol, MOMENTUM)
            + _count_present(rank_table, symbol, DURABILITY)
        )
        coverage_boost = 0.0
        if present_count >= 22:
            coverage_boost = 0.02
        elif present_count <= 10:
            coverage_boost = -0.03

        scores[symbol] = _clamp(score + coverage_boost, 0.0, 1.0)

    return scores