exp_1123

FORMULA_NAME = "Recovery Quality Contrarian 52-Week Hybrid (Arbitrated Relay, v1123)"
LOGIC_VARIANT_COUNT = 3
NOTES = """mode=explore; family=recovery-quality-contrarian-52w-hybrid
New hybrid family that fuses three orthogonal ideas into an explicit arbitration stack: 52-week drawdown contrarian entry, recovery/trend repair confirmation, and sparse-fundamental quality durability. The model does not average them mechanically. Instead it changes which sleeve can lead by regime and by stock state: strong tapes let repaired leaders graduate into momentum leadership, mixed tapes require quality-backed repair before deep drawdowns can rank, and risk-off tapes only allow contrarian rebounds through if low-vol durability and tradability are present. When recovery and contrarian signals conflict, repair state and quality decide whether a stock is an early turnaround or a falling knife.
Deliberate metric coverage: actively use one short-term shakeout metric, one medium-term momentum cluster, both recovery distance metrics, volatility, all three liquidity checks, both income metrics, two valuation metrics, three growth metrics, both quality metrics, and one size tilt. Deliberate weight-0 metrics this run: pe, return_12m_pct, eps_growth_pct, revenue_growth_pct, shares_outstanding, close, adj_close, high_52w, ma_200d, eps_ttm, revenue_ttm, operating_income_ttm, free_cash_flow_ttm. Correlated momentum and valuation columns are intentionally thinned, and sparse fundamentals are normalized by present weight so missing coverage does not auto-zero a name."""

RECOVERY_SLEEVE = {
    "from_52w_high_pct": (0.34, -1),
    "from_200d_ma_pct": (0.28, +1),
    "return_3m_pct": (0.16, +1),
    "return_1m_pct": (0.10, -1),
    "momentum_12_1_pct": (0.12, +1),
}

QUALITY_SLEEVE = {
    "operating_margin_pct": (0.24, +1),
    "free_cash_flow_margin_pct": (0.24, +1),
    "operating_income_growth_pct": (0.16, +1),
    "free_cash_flow_growth_pct": (0.16, +1),
    "forward_eps": (0.10, +1),
    "market_cap": (0.10, -1),
}

TRADABILITY_VALUE_SLEEVE = {
    "avg_daily_dollar_volume_3m": (0.18, +1),
    "avg_daily_volume_3m": (0.12, +1),
    "trading_days_3m": (0.10, +1),
    "forward_pe": (0.16, -1),
    "peg": (0.14, -1),
    "dividend_yield_ttm_pct": (0.10, +1),
    "dividend_ttm": (0.10, +1),
    "realized_vol_3m": (0.10, -1),
}

MOMENTUM_SLEEVE = {
    "return_6m_pct": (0.30, +1),
    "momentum_12_1_pct": (0.26, +1),
    "return_3m_pct": (0.18, +1),
    "from_200d_ma_pct": (0.16, +1),
    "realized_vol_3m": (0.10, -1),
}


def _weighted_score(symbol, z_cache, weights):
    total = 0.0
    present = 0.0
    for metric, spec in weights.items():
        weight, direction = spec
        value = z_cache[metric].get(symbol)
        if value is None:
            continue
        total += weight * direction * value
        present += weight
    if present <= 0.0:
        return None
    return total / present


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


def _safe_get(row, key):
    value = row.get(key)
    if value is None:
        return None
    return value


def _branch_name(regime):
    bull = regime.get("bull")
    breadth = regime.get("breadth")
    vol = regime.get("avg_realized_vol_3m")
    median_momo = regime.get("median_momentum_12_1_pct")
    median_repair = regime.get("median_from_200d_ma_pct")

    if (
        bull
        and breadth is not None and breadth >= 0.58
        and vol is not None and vol <= 0.33
        and median_momo is not None and median_momo >= 4.0
        and median_repair is not None and median_repair >= -0.02
    ):
        return "thrust"

    if (
        (not bull)
        or (breadth is not None and breadth < 0.46)
        or (vol is not None and vol >= 0.42)
        or (median_repair is not None and median_repair <= -0.08)
    ):
        return "defensive"

    return "selective"


def score_universe(stocks, regime, ctx):
    metrics = (
        "from_52w_high_pct",
        "from_200d_ma_pct",
        "return_1m_pct",
        "return_3m_pct",
        "return_6m_pct",
        "momentum_12_1_pct",
        "realized_vol_3m",
        "avg_daily_volume_3m",
        "avg_daily_dollar_volume_3m",
        "trading_days_3m",
        "dividend_yield_ttm_pct",
        "dividend_ttm",
        "forward_pe",
        "peg",
        "operating_income_growth_pct",
        "free_cash_flow_growth_pct",
        "forward_eps",
        "operating_margin_pct",
        "free_cash_flow_margin_pct",
        "market_cap",
    )
    z_cache = {}
    for metric in metrics:
        z_cache[metric] = ctx.z(metric)

    branch = _branch_name(regime)
    scores = {}

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

        recovery = _weighted_score(symbol, z_cache, RECOVERY_SLEEVE)
        quality = _weighted_score(symbol, z_cache, QUALITY_SLEEVE)
        tradability = _weighted_score(symbol, z_cache, TRADABILITY_VALUE_SLEEVE)
        momentum = _weighted_score(symbol, z_cache, MOMENTUM_SLEEVE)

        base_parts = 0.0
        base_weight = 0.0
        for value, weight in (
            (recovery, 1.0),
            (quality, 0.9),
            (tradability, 0.7),
            (momentum, 0.8),
        ):
            if value is None:
                continue
            base_parts += value * weight
            base_weight += weight
        if base_weight == 0.0:
            continue

        from_52w = _safe_get(row, "from_52w_high_pct")
        from_200d = _safe_get(row, "from_200d_ma_pct")
        ret_1m = _safe_get(row, "return_1m_pct")
        ret_3m = _safe_get(row, "return_3m_pct")
        ret_6m = _safe_get(row, "return_6m_pct")
        vol_3m = _safe_get(row, "realized_vol_3m")
        trading_days = _safe_get(row, "trading_days_3m")

        deep_drawdown = from_52w is not None and from_52w <= -18.0
        repaired = from_200d is not None and from_200d >= 2.0
        broken_trend = from_200d is not None and from_200d <= -6.0
        short_term_shakeout = ret_1m is not None and ret_1m <= -4.0
        medium_turn = ret_3m is not None and ret_3m >= 3.0
        sustained_trend = ret_6m is not None and ret_6m >= 8.0
        low_vol = vol_3m is not None and vol_3m <= 32.0
        tradable = trading_days is not None and trading_days >= 55.0

        arbitration = 0.0

        if branch == "thrust":
            # Reward names that have already repaired; deep drawdowns only work if they have turned.
            if repaired and sustained_trend:
                arbitration += 0.28
            if deep_drawdown and repaired and medium_turn:
                arbitration += 0.18
            if deep_drawdown and not repaired:
                arbitration -= 0.22
            if quality is not None and quality >= 0.35 and momentum is not None and momentum >= 0.20:
                arbitration += 0.14
            if short_term_shakeout and repaired:
                arbitration += 0.08

            branch_score = 0.40 * (momentum if momentum is not None else 0.0)
            branch_score += 0.28 * (recovery if recovery is not None else 0.0)
            branch_score += 0.20 * (quality if quality is not None else 0.0)
            branch_score += 0.12 * (tradability if tradability is not None else 0.0)

        elif branch == "selective":
            # Mixed tapes pay for recovery only if quality/tradability say the rebound is investable.
            if deep_drawdown and repaired and tradable:
                arbitration += 0.18
            if deep_drawdown and quality is not None and quality >= 0.25 and medium_turn:
                arbitration += 0.16
            if deep_drawdown and ((quality is not None and quality < -0.15) or broken_trend):
                arbitration -= 0.26
            if short_term_shakeout and repaired and quality is not None and quality >= 0.10:
                arbitration += 0.08
            if momentum is not None and momentum >= 0.35 and deep_drawdown is False:
                arbitration += 0.06

            branch_score = 0.34 * (recovery if recovery is not None else 0.0)
            branch_score += 0.30 * (quality if quality is not None else 0.0)
            branch_score += 0.20 * (tradability if tradability is not None else 0.0)
            branch_score += 0.16 * (momentum if momentum is not None else 0.0)

        else:
            # Risk-off only allows contrarian entries when durability and calm trading confirm.
            if deep_drawdown and repaired and low_vol and tradable:
                arbitration += 0.14
            if deep_drawdown and ((quality is not None and quality >= 0.30) and low_vol):
                arbitration += 0.12
            if deep_drawdown and not low_vol:
                arbitration -= 0.20
            if broken_trend:
                arbitration -= 0.16
            if quality is not None and quality >= 0.45 and tradability is not None and tradability >= 0.10:
                arbitration += 0.14

            branch_score = 0.38 * (quality if quality is not None else 0.0)
            branch_score += 0.24 * (tradability if tradability is not None else 0.0)
            branch_score += 0.24 * (recovery if recovery is not None else 0.0)
            branch_score += 0.14 * (momentum if momentum is not None else 0.0)

        sparse_penalty = 0.0
        missing_core = 0
        if recovery is None:
            missing_core += 1
        if quality is None:
            missing_core += 1
        if tradability is None:
            missing_core += 1
        if momentum is None:
            missing_core += 1
        if missing_core >= 3:
            sparse_penalty -= 0.18
        elif missing_core == 2:
            sparse_penalty -= 0.08

        final_score = (base_parts / base_weight) * 0.18 + branch_score * 0.82 + arbitration + sparse_penalty
        scores[symbol] = _clamp(final_score, -5.0, 5.0)

    return scores