exp_1185

FORMULA_NAME = "Contrarian 52-Week Regime Momentum Recovery Quality Hybrid (Escrow Referee, v1185)"
LOGIC_VARIANT_COUNT = 4
NOTES = """mode=explore; family=contrarian-52w-regime-momentum-recovery-quality-hybrid
New hybrid family built as an escrow-referee structure rather than a static blend: each stock first earns evidence inside three distinct sleeves, a washed-out 52-week contrarian sleeve, a trend-respecting momentum sleeve, and a recovery-quality sleeve, and then a branch-specific referee decides which edge is allowed to cash out. The arbitration is explicit and non-mechanical: deep drawdowns cannot win without repair evidence, momentum cannot dominate when extension outruns durability, and recovery candidates receive only partial credit unless quality, liquidity, and stabilization unlock the escrow. This makes the family structurally distinct from the parent relay/admission designs because sleeve conflict is settled through admissibility gates, conflict taxes, and branch-level release multipliers instead of simple dominance weights.
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; 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 stability and crowding moderator rather than a raw rank target. 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. Sparse fundamentals are normalized inside each sleeve so missing fields reduce confidence rather than forcing large-cap-only selection."""

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",
)


def score_universe(stocks, regime, ctx):
    def _get(stock, key, default=None):
        if isinstance(stock, dict):
            return stock.get(key, default)
        return default

    def _num(x):
        return isinstance(x, (int, float)) and x == x

    def _symbol(stock, idx):
        sym = _get(stock, "symbol", None)
        if sym is None:
            sym = _get(stock, "ticker", None)
        if sym is None:
            sym = "STK_" + str(idx)
        return sym

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

    def _avg(vals):
        total = 0.0
        count = 0
        for v in vals:
            if _num(v):
                total += v
                count += 1
        if count == 0:
            return None
        return total / count

    def _metric_rank(stock, metric, higher_is_better, cache):
        ranks = cache.get(metric)
        if ranks is None:
            vals = []
            for j, s in enumerate(stocks):
                v = _get(s, metric, None)
                if _num(v):
                    vals.append((v, j))
            vals.sort(key=lambda x: x[0])
            n = len(vals)
            ranks = {}
            if n == 1:
                ranks[vals[0][1]] = 0.5
            elif n > 1:
                for pos, pair in enumerate(vals):
                    ranks[pair[1]] = pos / float(n - 1)
            cache[metric] = ranks
        r = ranks.get(stock["_idx"])
        if r is None:
            return None
        return r if higher_is_better else (1.0 - r)

    def _blend(stock, metric_defs, cache):
        total = 0.0
        weight = 0.0
        for metric, w, sign in metric_defs:
            r = _metric_rank(stock, metric, sign > 0, cache)
            if r is not None:
                total += w * r
                weight += w
        if weight <= 0.0:
            return None
        return total / weight

    def _coverage(stock, metrics):
        seen = 0
        for metric in metrics:
            if _num(_get(stock, metric, None)):
                seen += 1
        if not metrics:
            return 0.0
        return seen / float(len(metrics))

    def _regime_branch(regime_obj):
        text = ""
        risk_off = False
        high_vol = False
        weak_trend = False
        if isinstance(regime_obj, str):
            text = regime_obj.lower()
        elif isinstance(regime_obj, dict):
            for key in (
                "regime",
                "label",
                "state",
                "market_regime",
                "trend_regime",
                "vol_regime",
                "risk_regime",
            ):
                val = regime_obj.get(key)
                if isinstance(val, str):
                    text += " " + val.lower()
            risk_off = bool(regime_obj.get("risk_off")) or bool(regime_obj.get("defensive"))
            high_vol = bool(regime_obj.get("high_vol")) or bool(regime_obj.get("volatile"))
            weak_trend = bool(regime_obj.get("weak_trend")) or bool(regime_obj.get("bearish"))
            vix_like = regime_obj.get("volatility", None)
            if _num(vix_like) and vix_like > 0.6:
                high_vol = True
            breadth = regime_obj.get("breadth", None)
            if _num(breadth) and breadth < -0.15:
                weak_trend = True
            trend = regime_obj.get("trend", None)
            if _num(trend) and trend < -0.1:
                weak_trend = True
        if "stress" in text or "panic" in text or "crash" in text:
            return "stressed"
        if "bear" in text or "defensive" in text or "risk-off" in text or risk_off:
            return "defensive"
        if "recovery" in text or "repair" in text or "transition" in text:
            return "recovery"
        if "bull" in text or "uptrend" in text or "risk-on" in text:
            return "bull"
        if high_vol and weak_trend:
            return "stressed"
        if weak_trend or risk_off:
            return "defensive"
        if high_vol:
            return "recovery"
        return "bull"

    stocks = list(stocks)
    for i, stock in enumerate(stocks):
        stock["_idx"] = i

    cache = {}

    momentum_cluster = (
        ("momentum_12_1_pct", 0.27, +1),
        ("return_6m_pct", 0.24, +1),
        ("return_3m_pct", 0.18, +1),
        ("return_1m_pct", 0.11, +1),
        ("return_12m_pct", 0.08, +1),
        ("from_200d_ma_pct", 0.12, +1),
    )
    contrarian_cluster = (
        ("from_52w_high_pct", 0.34, -1),
        ("from_200d_ma_pct", 0.22, -1),
        ("return_1m_pct", 0.10, -1),
        ("return_3m_pct", 0.08, -1),
        ("realized_vol_3m", 0.08, -1),
        ("avg_daily_dollar_volume_3m", 0.08, +1),
        ("trading_days_3m", 0.10, +1),
    )
    repair_cluster = (
        ("return_1m_pct", 0.16, +1),
        ("return_3m_pct", 0.16, +1),
        ("from_200d_ma_pct", 0.20, +1),
        ("from_52w_high_pct", 0.14, +1),
        ("eps_growth_pct", 0.08, +1),
        ("revenue_growth_pct", 0.08, +1),
        ("operating_income_growth_pct", 0.08, +1),
        ("free_cash_flow_growth_pct", 0.10, +1),
    )
    quality_cluster = (
        ("operating_margin_pct", 0.22, +1),
        ("free_cash_flow_margin_pct", 0.22, +1),
        ("dividend_yield_ttm_pct", 0.08, +1),
        ("dividend_ttm", 0.05, +1),
        ("pe", 0.09, -1),
        ("forward_pe", 0.10, -1),
        ("peg", 0.09, -1),
        ("forward_eps", 0.07, +1),
        ("market_cap", 0.08, +1),
    )
    liquidity_cluster = (
        ("avg_daily_volume_3m", 0.28, +1),
        ("avg_daily_dollar_volume_3m", 0.44, +1),
        ("trading_days_3m", 0.28, +1),
    )
    stability_cluster = (
        ("realized_vol_3m", 0.35, -1),
        ("avg_daily_dollar_volume_3m", 0.20, +1),
        ("market_cap", 0.20, +1),
        ("operating_margin_pct", 0.12, +1),
        ("free_cash_flow_margin_pct", 0.13, +1),
    )

    branch = _regime_branch(regime)
    scores = {}

    for i, stock in enumerate(stocks):
        sym = _symbol(stock, i)

        mom = _blend(stock, momentum_cluster, cache)
        contra = _blend(stock, contrarian_cluster, cache)
        repair = _blend(stock, repair_cluster, cache)
        quality = _blend(stock, quality_cluster, cache)
        liquid = _blend(stock, liquidity_cluster, cache)
        stable = _blend(stock, stability_cluster, cache)

        if mom is None:
            mom = 0.5
        if contra is None:
            contra = 0.5
        if repair is None:
            repair = 0.5
        if quality is None:
            quality = 0.5
        if liquid is None:
            liquid = 0.5
        if stable is None:
            stable = 0.5

        drawdown = _metric_rank(stock, "from_52w_high_pct", False, cache)
        above_200 = _metric_rank(stock, "from_200d_ma_pct", True, cache)
        cheapness = _avg(
            (
                _metric_rank(stock, "pe", False, cache),
                _metric_rank(stock, "forward_pe", False, cache),
                _metric_rank(stock, "peg", False, cache),
            )
        )
        growth = _avg(
            (
                _metric_rank(stock, "eps_growth_pct", True, cache),
                _metric_rank(stock, "revenue_growth_pct", True, cache),
                _metric_rank(stock, "operating_income_growth_pct", True, cache),
                _metric_rank(stock, "free_cash_flow_growth_pct", True, cache),
                _metric_rank(stock, "forward_eps", True, cache),
            )
        )
        if drawdown is None:
            drawdown = 0.5
        if above_200 is None:
            above_200 = 0.5
        if cheapness is None:
            cheapness = 0.5
        if growth is None:
            growth = 0.5

        contrarian_admissible = (
            0.55 * drawdown
            + 0.25 * repair
            + 0.10 * liquid
            + 0.10 * stable
        )
        momentum_admissible = (
            0.58 * mom
            + 0.17 * above_200
            + 0.15 * stable
            + 0.10 * quality
        )
        recovery_admissible = (
            0.34 * repair
            + 0.22 * quality
            + 0.14 * growth
            + 0.15 * stable
            + 0.15 * liquid
        )

        extension_tax = _clamp(mom - drawdown - 0.18, 0.0, 0.35)
        broken_tax = _clamp(drawdown - repair - 0.10, 0.0, 0.35)
        junk_tax = _clamp(0.52 - quality, 0.0, 0.25) + _clamp(0.48 - liquid, 0.0, 0.20)
        conflict_tax = 0.0
        if mom > 0.62 and contra > 0.62:
            conflict_tax += 0.08
        if drawdown > 0.70 and above_200 < 0.35:
            conflict_tax += 0.08

        contrarian_edge = (
            0.48 * contra
            + 0.22 * repair
            + 0.12 * cheapness
            + 0.10 * quality
            + 0.08 * liquid
            - 0.55 * broken_tax
        )
        momentum_edge = (
            0.56 * mom
            + 0.14 * above_200
            + 0.12 * quality
            + 0.10 * growth
            + 0.08 * liquid
            - 0.60 * extension_tax
        )
        recovery_edge = (
            0.30 * repair
            + 0.24 * quality
            + 0.16 * growth
            + 0.10 * cheapness
            + 0.10 * liquid
            + 0.10 * stable
            - 0.30 * broken_tax
        )

        contra_release = _clamp((contrarian_admissible - 0.45) / 0.35, 0.0, 1.0)
        mom_release = _clamp((momentum_admissible - 0.48) / 0.32, 0.0, 1.0)
        repair_release = _clamp((recovery_admissible - 0.46) / 0.34, 0.0, 1.0)

        released_contra = contrarian_edge * (0.35 + 0.65 * contra_release)
        released_mom = momentum_edge * (0.35 + 0.65 * mom_release)
        released_recovery = recovery_edge * (0.35 + 0.65 * repair_release)

        if branch == "bull":
            branch_score = (
                0.52 * released_mom
                + 0.22 * released_recovery
                + 0.16 * released_contra
                + 0.10 * stable
            )
            branch_score -= 0.10 * broken_tax + 0.06 * conflict_tax
        elif branch == "recovery":
            branch_score = (
                0.41 * released_recovery
                + 0.29 * released_mom
                + 0.20 * released_contra
                + 0.10 * cheapness
            )
            branch_score -= 0.07 * extension_tax + 0.05 * conflict_tax
        elif branch == "stressed":
            branch_score = (
                0.39 * released_contra
                + 0.31 * released_recovery
                + 0.18 * stable
                + 0.12 * quality
            )
            branch_score -= 0.12 * junk_tax + 0.05 * extension_tax
        else:
            branch_score = (
                0.37 * released_recovery
                + 0.25 * released_contra
                + 0.20 * quality
                + 0.10 * stable
                + 0.08 * cheapness
            )
            branch_score -= 0.10 * junk_tax + 0.06 * extension_tax

        primary = released_mom
        secondary = released_recovery
        if released_contra > primary:
            secondary = primary
            primary = released_contra
        elif released_contra > secondary:
            secondary = released_contra
        if released_recovery > primary:
            secondary = primary
            primary = released_recovery
        elif released_recovery > secondary:
            secondary = released_recovery

        agreement_bonus = 0.0
        if primary > 0.58 and secondary > 0.54:
            agreement_bonus = 0.06
        if released_mom > 0.60 and released_recovery > 0.55 and above_200 > 0.55:
            agreement_bonus += 0.04
        if released_contra > 0.60 and repair > 0.55 and quality > 0.52:
            agreement_bonus += 0.04

        metric_coverage = _coverage(stock, ACTIVE_METRICS)
        coverage_bonus = 0.05 * _clamp((metric_coverage - 0.35) / 0.45, 0.0, 1.0)
        sparse_penalty = 0.08 * _clamp(0.28 - metric_coverage, 0.0, 0.28) / 0.28

        final_score = branch_score + agreement_bonus + coverage_bonus - conflict_tax - sparse_penalty
        scores[sym] = final_score

    for stock in stocks:
        if "_idx" in stock:
            del stock["_idx"]

    return scores