exp_1104

FORMULA_NAME = "Contrarian 52-Week Recovery with Quality Arbitration (v1104)"
LOGIC_VARIANT_COUNT = 3
NOTES = """mode=explore; family=contrarian-52w-recovery-quality-hybrid
New hybrid family that combines the contrarian-52w recovery ladder with the recovery-quality relay, but not as a flat average: each regime runs an explicit arbitration between a price-repair sleeve and a business-durability sleeve so deep rebounds only survive when quality/liquidity evidence is good enough, while cleaner recoveries can outrank mediocre fundamentals in stronger tapes.
Deliberate metric coverage: actively use one recovery cluster (from_52w_high_pct plus from_200d_ma_pct), one momentum cluster (return_3m_pct, return_6m_pct, momentum_12_1_pct, with return_12m_pct only as a repair confirmation), one volatility check, two liquidity checks, one income check, one valuation check, one growth cluster, one quality cluster, and one size tilt. Deliberately weight return_1m_pct, avg_daily_volume_3m, dividend_ttm, pe, eps_growth_pct, shares_outstanding, close, adj_close, high_52w, ma_200d, eps_ttm, revenue_ttm, operating_income_ttm, and free_cash_flow_ttm at zero this run to avoid collapsing into the same parent stack while still covering the full metric menu consciously. Sparse fundamentals are normalized by present weight before arbitration."""

CALM_BULL = {
    "from_52w_high_pct": (0.18, -1),
    "from_200d_ma_pct": (0.14, +1),
    "return_6m_pct": (0.10, +1),
    "momentum_12_1_pct": (0.08, +1),
    "realized_vol_3m": (0.05, -1),
    "avg_daily_dollar_volume_3m": (0.05, +1),
    "dividend_yield_ttm_pct": (0.03, +1),
    "market_cap": (0.04, -1),
}

STRESSED_BULL = {
    "from_52w_high_pct": (0.12, -1),
    "from_200d_ma_pct": (0.14, +1),
    "return_3m_pct": (0.08, +1),
    "momentum_12_1_pct": (0.07, +1),
    "realized_vol_3m": (0.07, -1),
    "avg_daily_dollar_volume_3m": (0.07, +1),
    "trading_days_3m": (0.05, +1),
    "free_cash_flow_margin_pct": (0.08, +1),
    "operating_margin_pct": (0.06, +1),
    "free_cash_flow_growth_pct": (0.05, +1),
    "forward_pe": (0.05, -1),
}

RISK_OFF = {
    "from_52w_high_pct": (0.08, -1),
    "from_200d_ma_pct": (0.15, +1),
    "return_12m_pct": (0.05, +1),
    "realized_vol_3m": (0.11, -1),
    "avg_daily_dollar_volume_3m": (0.08, +1),
    "trading_days_3m": (0.06, +1),
    "dividend_yield_ttm_pct": (0.06, +1),
    "forward_pe": (0.05, -1),
    "revenue_growth_pct": (0.05, +1),
    "operating_income_growth_pct": (0.06, +1),
    "free_cash_flow_growth_pct": (0.07, +1),
    "forward_eps": (0.04, +1),
    "operating_margin_pct": (0.08, +1),
    "free_cash_flow_margin_pct": (0.10, +1),
}


def _regime_book(regime):
    if regime.get("bull"):
        if regime.get("avg_realized_vol_3m", 0) > 28 or regime.get("breadth", 0) < 0.62:
            return STRESSED_BULL, "stressed_bull"
        return CALM_BULL, "calm_bull"
    return RISK_OFF, "risk_off"


def _bounded(value, low, high):
    if value < low:
        return low
    if value > high:
        return high
    return value


def score_universe(stocks, regime, ctx):
    book, branch = _regime_book(regime)
    zmaps = {metric: ctx.z(metric) for metric in book}
    scores = {}

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

        base_total = 0.0
        base_weight = 0.0
        for metric, (weight, sign) in book.items():
            z = zmaps[metric].get(sym)
            if z is not None:
                base_total += weight * sign * z
                base_weight += weight
        if base_weight > 0:
            total = base_total / base_weight
        else:
            total = 0.0

        drawdown = row.get("from_52w_high_pct")
        trend = row.get("from_200d_ma_pct")
        ret3 = row.get("return_3m_pct")
        ret6 = row.get("return_6m_pct")
        ret12 = row.get("return_12m_pct")
        mom = row.get("momentum_12_1_pct")
        vol = row.get("realized_vol_3m")
        dollar_vol = row.get("avg_daily_dollar_volume_3m")
        trading_days = row.get("trading_days_3m")
        div_yield = row.get("dividend_yield_ttm_pct")
        forward_pe = row.get("forward_pe")
        rev_growth = row.get("revenue_growth_pct")
        op_growth = row.get("operating_income_growth_pct")
        fcf_growth = row.get("free_cash_flow_growth_pct")
        forward_eps = row.get("forward_eps")
        op_margin = row.get("operating_margin_pct")
        fcf_margin = row.get("free_cash_flow_margin_pct")
        cap = row.get("market_cap")

        recovery_score = 0.0
        recovery_weight = 0.0

        if drawdown is not None:
            recovery_weight += 1.0
            if branch == "calm_bull":
                if drawdown < -42:
                    recovery_score -= 1.00
                elif drawdown < -30:
                    recovery_score += 0.45
                elif drawdown < -18:
                    recovery_score += 1.10
                elif drawdown < -8:
                    recovery_score += 0.60
                elif drawdown < -3:
                    recovery_score += 0.10
                else:
                    recovery_score -= 0.30
            elif branch == "stressed_bull":
                if drawdown < -45:
                    recovery_score -= 0.85
                elif drawdown < -32:
                    recovery_score += 0.20
                elif drawdown < -16:
                    recovery_score += 0.75
                elif drawdown < -6:
                    recovery_score += 0.55
                else:
                    recovery_score -= 0.20
            else:
                if drawdown < -30:
                    recovery_score -= 0.55
                elif drawdown < -16:
                    recovery_score += 0.25
                elif drawdown < -5:
                    recovery_score += 0.70
                else:
                    recovery_score -= 0.15

        if trend is not None:
            recovery_weight += 1.0
            if branch == "calm_bull":
                if trend > 14:
                    recovery_score += 0.85
                elif trend > 4:
                    recovery_score += 0.45
                elif trend < -4:
                    recovery_score -= 0.90
            elif branch == "stressed_bull":
                if trend > 10:
                    recovery_score += 0.65
                elif trend > 1:
                    recovery_score += 0.35
                elif trend < -3:
                    recovery_score -= 0.85
            else:
                if trend > 8:
                    recovery_score += 0.70
                elif trend > 2:
                    recovery_score += 0.35
                elif trend < 0:
                    recovery_score -= 0.90

        if ret3 is not None:
            recovery_weight += 0.7
            if ret3 > 16:
                recovery_score += 0.55
            elif ret3 > 4:
                recovery_score += 0.30
            elif ret3 < -10:
                recovery_score -= 0.65
            elif ret3 < 0:
                recovery_score -= 0.20

        if ret6 is not None:
            recovery_weight += 0.9
            if ret6 > 20:
                recovery_score += 0.60
            elif ret6 > 8:
                recovery_score += 0.35
            elif ret6 < -8:
                recovery_score -= 0.70
            elif ret6 < 0:
                recovery_score -= 0.25

        if mom is not None:
            recovery_weight += 0.8
            if mom >= 3 and mom <= 24:
                recovery_score += 0.50
            elif mom > 24:
                recovery_score += 0.18
            elif mom < -12:
                recovery_score -= 0.70
            elif mom < 0:
                recovery_score -= 0.20

        if ret12 is not None:
            recovery_weight += 0.5
            if branch == "risk_off":
                if ret12 > 8:
                    recovery_score += 0.30
                elif ret12 < -20:
                    recovery_score -= 0.55
            else:
                if ret12 > 12:
                    recovery_score += 0.18
                elif ret12 < -25:
                    recovery_score -= 0.35

        if vol is not None:
            recovery_weight += 0.6
            if vol < 22:
                recovery_score += 0.25
            elif vol > 44:
                recovery_score -= 0.45
            elif vol > 34:
                recovery_score -= 0.18

        if recovery_weight > 0:
            recovery_score = recovery_score / recovery_weight

        quality_score = 0.0
        quality_weight = 0.0

        if fcf_margin is not None:
            quality_weight += 1.1
            if fcf_margin > 12:
                quality_score += 1.00
            elif fcf_margin > 5:
                quality_score += 0.55
            elif fcf_margin < 0:
                quality_score -= 1.00
            elif fcf_margin < 3:
                quality_score -= 0.25

        if op_margin is not None:
            quality_weight += 0.9
            if op_margin > 18:
                quality_score += 0.80
            elif op_margin > 8:
                quality_score += 0.40
            elif op_margin < 0:
                quality_score -= 0.90
            elif op_margin < 4:
                quality_score -= 0.20

        growth_balance = 0.0
        growth_count = 0
        for metric in (rev_growth, op_growth, fcf_growth):
            if metric is not None:
                growth_count += 1
                if metric > 18:
                    growth_balance += 0.80
                elif metric > 6:
                    growth_balance += 0.35
                elif metric < -12:
                    growth_balance -= 0.90
                elif metric < 0:
                    growth_balance -= 0.30
        if growth_count > 0:
            quality_weight += 1.0
            quality_score += growth_balance / growth_count

        if forward_eps is not None:
            quality_weight += 0.5
            if forward_eps > 0:
                quality_score += 0.25
            else:
                quality_score -= 0.80

        if forward_pe is not None:
            quality_weight += 0.6
            if forward_pe > 0 and forward_pe < 18:
                quality_score += 0.35
            elif forward_pe > 40:
                quality_score -= 0.45

        if div_yield is not None:
            quality_weight += 0.4
            if div_yield >= 0.7 and div_yield <= 4.5:
                quality_score += 0.22
            elif div_yield > 5.5:
                quality_score -= 0.20
            elif div_yield == 0 and branch == "risk_off":
                quality_score -= 0.12

        if dollar_vol is not None:
            quality_weight += 0.5
            if dollar_vol > 30000000:
                quality_score += 0.35
            elif dollar_vol > 10000000:
                quality_score += 0.18
            elif dollar_vol < 3000000:
                quality_score -= 0.45

        if trading_days is not None:
            quality_weight += 0.4
            if trading_days >= 62:
                quality_score += 0.18
            elif trading_days <= 57:
                quality_score -= 0.35

        if quality_weight > 0:
            quality_score = quality_score / quality_weight

        if branch == "calm_bull":
            recovery_mix = 0.72
            quality_mix = 0.28
        elif branch == "stressed_bull":
            recovery_mix = 0.52
            quality_mix = 0.48
        else:
            recovery_mix = 0.34
            quality_mix = 0.66

        total += recovery_mix * recovery_score + quality_mix * quality_score

        if recovery_weight > 0 and quality_weight > 0:
            if recovery_score > 0.45 and quality_score > 0.25:
                total += 0.28
            elif recovery_score > 0.55 and quality_score < -0.20:
                total -= 0.48
            elif recovery_score < -0.25 and quality_score > 0.45 and branch != "calm_bull":
                total += 0.10
            elif recovery_score < -0.35 and quality_score < -0.20:
                total -= 0.22
        elif recovery_weight > 0 and quality_weight == 0 and branch != "calm_bull":
            total -= 0.12

        if branch == "calm_bull":
            if cap is not None:
                if cap < 3000000000:
                    total += 0.18
                elif cap < 10000000000:
                    total += 0.08
                elif cap > 200000000000:
                    total -= 0.10

            if drawdown is not None and trend is not None:
                if drawdown < -12 and drawdown > -28 and trend > 5:
                    total += 0.22

        elif branch == "stressed_bull":
            if vol is not None and vol > 40:
                total -= 0.18
            if quality_weight > 0 and quality_score > 0.35 and drawdown is not None and drawdown < -10:
                total += 0.16

        else:
            if vol is not None:
                if vol < 24:
                    total += 0.14
                elif vol > 34:
                    total -= 0.22
            if trend is not None and trend < 0:
                total -= 0.20
            if quality_weight > 0 and quality_score > 0.40 and drawdown is not None and drawdown > -4:
                total += 0.14

        total += 0.10 * _bounded(recovery_score - quality_score, -1.5, 1.5) * (0.25 if branch == "risk_off" else 0.55)

        scores[sym] = total

    return scores