exp_1127

FORMULA_NAME = "Regime Momentum Recovery Quality Contrarian 52-Week Hybrid (Arbitrated State Relay, v1127)"
LOGIC_VARIANT_COUNT = 4
NOTES = """mode=explore; family=regime-momentum-recovery-quality-contrarian-52w-hybrid
New hybrid family that combines the strongest orthogonal edges from regime-momentum-quality-value, recovery-quality-contrarian-52w-hybrid, and contrarian-52w into a four-branch arbitration system rather than a blended average. In strong tapes, repaired names with real momentum are allowed to lead; in mixed tapes, quality-backed recovery gets priority and deep drawdown names must prove trend repair before they can outrank; in risk-off tapes, only durable low-vol names with tradability and modest value support survive; in washed-out rebound states, contrarian entries are allowed back in, but only when short-term repair is visible and the stock is not simply a falling knife. Conflicts between momentum and contrarian signals are resolved explicitly through stock-state gates based on 52-week drawdown, 200-day distance, and 3-month return.
Deliberate metric coverage this run: momentum uses 12_1 plus 6m in leadership branches and 3m only for rebound confirmation; trend/recovery uses both 200d distance and 52-week-high distance in every branch; volatility is active only in defensive and rebound branches; liquidity uses trading_days plus dollar volume while share volume is deliberately zeroed; income uses dividend yield only in the defensive branch; valuation uses forward_pe and peg as a selective support block rather than a global anchor; growth uses operating-income growth and free-cash-flow growth while revenue/eps growth are deliberately zeroed this run; quality uses operating margin and free-cash-flow margin across non-pure-momentum branches; size uses market_cap only as a modest bull-rebound tilt. Deliberate weight-0 metrics this run: return_1m_pct, return_12m_pct, avg_daily_volume_3m, pe, revenue_growth_pct, eps_growth_pct, forward_eps, shares_outstanding, close, adj_close, high_52w, ma_200d, eps_ttm, revenue_ttm, operating_income_ttm, free_cash_flow_ttm."""

BULL_LEADERS = {
    "momentum_12_1_pct": (0.25, +1),
    "return_6m_pct": (0.19, +1),
    "from_200d_ma_pct": (0.17, +1),
    "from_52w_high_pct": (0.08, -1),
    "operating_income_growth_pct": (0.10, +1),
    "free_cash_flow_margin_pct": (0.09, +1),
    "forward_pe": (0.07, -1),
    "avg_daily_dollar_volume_3m": (0.05, +1),
}

MIXED_REPAIR = {
    "from_200d_ma_pct": (0.21, +1),
    "from_52w_high_pct": (0.19, -1),
    "return_3m_pct": (0.13, +1),
    "momentum_12_1_pct": (0.08, +1),
    "operating_margin_pct": (0.12, +1),
    "free_cash_flow_margin_pct": (0.10, +1),
    "free_cash_flow_growth_pct": (0.08, +1),
    "peg": (0.05, -1),
    "trading_days_3m": (0.04, +1),
}

RISK_OFF_DURABLE = {
    "realized_vol_3m": (0.20, -1),
    "from_200d_ma_pct": (0.16, +1),
    "from_52w_high_pct": (0.09, -1),
    "operating_margin_pct": (0.15, +1),
    "free_cash_flow_margin_pct": (0.11, +1),
    "dividend_yield_ttm_pct": (0.07, +1),
    "forward_pe": (0.08, -1),
    "peg": (0.05, -1),
    "trading_days_3m": (0.05, +1),
    "avg_daily_dollar_volume_3m": (0.04, +1),
}

WASHOUT_REBOUND = {
    "from_52w_high_pct": (0.27, -1),
    "from_200d_ma_pct": (0.17, +1),
    "return_3m_pct": (0.15, +1),
    "momentum_12_1_pct": (0.08, +1),
    "realized_vol_3m": (0.09, -1),
    "operating_margin_pct": (0.08, +1),
    "free_cash_flow_growth_pct": (0.07, +1),
    "market_cap": (0.05, -1),
    "avg_daily_dollar_volume_3m": (0.04, +1),
}


def score_universe(stocks, regime, ctx):
    def _safe_float(value):
        if value is None:
            return None
        try:
            value = float(value)
        except (TypeError, ValueError):
            return None
        if value != value:
            return None
        return value

    def _metric_value(stock, metric):
        return _safe_float(stock.get(metric))

    def _regime_name(value):
        if value is None:
            return ""
        return str(value).strip().lower()

    def _percentile_map(universe, metric, direction):
        vals = []
        for stock in universe:
            v = _metric_value(stock, metric)
            if v is not None:
                vals.append(v)
        if not vals:
            return {}

        vals = sorted(vals)
        n = len(vals)
        ranks = {}
        i = 0
        while i < n:
            j = i + 1
            while j < n and vals[j] == vals[i]:
                j += 1
            if n == 1:
                pct = 0.5
            else:
                pct = ((i + j - 1) * 0.5) / (n - 1)
            ranks[vals[i]] = pct
            i = j

        out = {}
        for stock in universe:
            sym = stock.get("symbol")
            if not sym:
                continue
            v = _metric_value(stock, metric)
            if v is None:
                continue
            pct = ranks.get(v, 0.5)
            out[sym] = pct if direction > 0 else 1.0 - pct
        return out

    def _weighted_score(stock, sleeve, rank_cache):
        total = 0.0
        present = 0.0
        sym = stock.get("symbol")
        if not sym:
            return 0.0
        for metric, spec in sleeve.items():
            weight, direction = spec
            if weight <= 0:
                continue
            cache_key = metric + "|" + str(direction)
            metric_ranks = rank_cache.get(cache_key)
            if metric_ranks is None:
                metric_ranks = _percentile_map(stocks, metric, direction)
                rank_cache[cache_key] = metric_ranks
            if sym in metric_ranks:
                total += weight * metric_ranks[sym]
                present += weight
        if present <= 0:
            return 0.0
        return total / present

    def _branch_for(stock, regime_name):
        d52 = _metric_value(stock, "from_52w_high_pct")
        d200 = _metric_value(stock, "from_200d_ma_pct")
        r3 = _metric_value(stock, "return_3m_pct")
        m12 = _metric_value(stock, "momentum_12_1_pct")

        deep_drawdown = d52 is not None and d52 <= -0.22
        repaired_trend = d200 is not None and d200 >= -0.02
        strong_trend = d200 is not None and d200 >= 0.06
        positive_rebound = r3 is not None and r3 >= 0.04
        strong_momentum = m12 is not None and m12 >= 0.0

        risk_words = ("risk", "off", "bear", "defen", "drawdown", "crash")
        bull_words = ("bull", "risk_on", "uptrend", "strong", "momo")
        mixed_words = ("mixed", "neutral", "sideways", "chop", "range")

        is_risk_off = False
        is_bull = False
        is_mixed = False

        for word in risk_words:
            if word in regime_name:
                is_risk_off = True
                break
        if not is_risk_off:
            for word in bull_words:
                if word in regime_name:
                    is_bull = True
                    break
        if not is_risk_off and not is_bull:
            for word in mixed_words:
                if word in regime_name:
                    is_mixed = True
                    break

        if is_risk_off:
            if deep_drawdown and repaired_trend and positive_rebound:
                return "washout_rebound"
            return "risk_off_durable"

        if is_bull:
            if repaired_trend and strong_trend and strong_momentum:
                return "bull_leaders"
            if deep_drawdown and positive_rebound:
                return "washout_rebound"
            return "mixed_repair"

        if is_mixed:
            if deep_drawdown and repaired_trend and positive_rebound:
                return "washout_rebound"
            return "mixed_repair"

        if deep_drawdown and repaired_trend and positive_rebound:
            return "washout_rebound"
        if repaired_trend and strong_momentum:
            return "bull_leaders"
        return "mixed_repair"

    sleeve_map = {
        "bull_leaders": BULL_LEADERS,
        "mixed_repair": MIXED_REPAIR,
        "risk_off_durable": RISK_OFF_DURABLE,
        "washout_rebound": WASHOUT_REBOUND,
    }

    regime_name = _regime_name(regime)
    rank_cache = {}
    scores = {}

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

        branch = _branch_for(stock, regime_name)
        sleeve = sleeve_map[branch]
        base = _weighted_score(stock, sleeve, rank_cache)

        d52 = _metric_value(stock, "from_52w_high_pct")
        d200 = _metric_value(stock, "from_200d_ma_pct")
        r3 = _metric_value(stock, "return_3m_pct")
        vol = _metric_value(stock, "realized_vol_3m")
        opm = _metric_value(stock, "operating_margin_pct")
        fcfm = _metric_value(stock, "free_cash_flow_margin_pct")

        bonus = 0.0

        if branch == "bull_leaders":
            if d200 is not None and d200 > 0.10:
                bonus += 0.035
            if d52 is not None and d52 > -0.12:
                bonus += 0.020
            if r3 is not None and r3 < -0.02:
                bonus -= 0.030

        elif branch == "mixed_repair":
            if d52 is not None and -0.35 <= d52 <= -0.10:
                bonus += 0.040
            if d200 is not None and d200 < -0.08:
                bonus -= 0.045
            if opm is not None and opm < 0:
                bonus -= 0.020

        elif branch == "risk_off_durable":
            if vol is not None and vol > 0.42:
                bonus -= 0.050
            if d200 is not None and d200 < -0.05:
                bonus -= 0.030
            if fcfm is not None and fcfm > 0:
                bonus += 0.020

        elif branch == "washout_rebound":
            if d52 is not None and -0.45 <= d52 <= -0.18:
                bonus += 0.050
            if d200 is not None and d200 < -0.12:
                bonus -= 0.060
            if r3 is not None and r3 < 0:
                bonus -= 0.035

        scores[sym] = base + bonus

    return scores