exp_1182

FORMULA_NAME = "Recovery Quality Contrarian 52-Week Hybrid (Quality Quorum Switchboard, v1182)"
LOGIC_VARIANT_COUNT = 3
NOTES = """mode=explore; family=recovery-quality-contrarian-52w-hybrid
New hybrid family that combines the champion recovery-quality-contrarian stack with the strong bull shallower-sweet-spot logic from contrarian-52w, but changes the arbitration mechanism completely. Instead of a relay or barbell, this script runs a quality quorum switchboard: contrarian 52-week pullbacks, repair/trend evidence, and defensive durability each propose a candidate state, then the active regime decides which state may lead and which must merely confirm. Bull tapes allow shallower pullbacks to outrank only when repair is already visible; transition tapes require a fundamental quorum before deep drawdowns can compete; defensive tapes keep the contrarian sleeve on a short leash and let low-vol income-backed durability arbitrate conflicts. When recovery and contrarian signals disagree, the switchboard classifies the name as a repaired rebound, a sweet-spot pullback, or a falling knife and scores accordingly.
Deliberate metric coverage this run: momentum uses return_1m_pct as a shakeout input plus return_3m_pct, return_6m_pct, and momentum_12_1_pct; trend/recovery uses both from_200d_ma_pct and from_52w_high_pct; volatility uses realized_vol_3m; liquidity uses avg_daily_volume_3m and trading_days_3m; income uses dividend_yield_ttm_pct and dividend_ttm; valuation uses pe and peg; growth uses revenue_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 mild small-cap rebound tilt. Deliberate weight-0 metrics this run: return_12m_pct, avg_daily_dollar_volume_3m, forward_pe, eps_growth_pct, operating_income_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 evidence so missing coverage does not auto-zero a name."""

PULLBACK_REPAIR = {
    "from_52w_high_pct": (0.24, -1),
    "return_1m_pct": (0.16, -1),
    "return_3m_pct": (0.17, +1),
    "return_6m_pct": (0.12, +1),
    "from_200d_ma_pct": (0.15, +1),
    "momentum_12_1_pct": (0.10, +1),
    "market_cap": (0.06, -1),
}

REPAIR_LEADERSHIP = {
    "from_200d_ma_pct": (0.24, +1),
    "return_3m_pct": (0.20, +1),
    "momentum_12_1_pct": (0.16, +1),
    "return_6m_pct": (0.10, +1),
    "forward_eps": (0.10, +1),
    "revenue_growth_pct": (0.10, +1),
    "free_cash_flow_growth_pct": (0.10, +1),
}

DURABLE_INCOME = {
    "realized_vol_3m": (0.17, -1),
    "operating_margin_pct": (0.15, +1),
    "free_cash_flow_margin_pct": (0.14, +1),
    "dividend_yield_ttm_pct": (0.10, +1),
    "dividend_ttm": (0.08, +1),
    "pe": (0.10, -1),
    "peg": (0.07, -1),
    "avg_daily_volume_3m": (0.10, +1),
    "trading_days_3m": (0.09, +1),
}


def _to_float(value):
    if value is None or isinstance(value, bool):
        return None
    try:
        value = float(value)
    except Exception:
        return None
    if value != value:
        return None
    return value


def _metric(stock, name):
    return _to_float(stock.get(name))


def _rank_map(stocks, metric, direction):
    pairs = []
    for stock in stocks:
        symbol = stock.get("symbol")
        if not symbol:
            continue
        value = _metric(stock, metric)
        if value is not None:
            pairs.append((symbol, value))
    if not pairs:
        return {}
    pairs.sort(key=lambda item: item[1])
    count = len(pairs)
    if count == 1:
        return {pairs[0][0]: 1.0}
    out = {}
    denom = float(count - 1)
    i = 0
    while i < count:
        j = i + 1
        value = pairs[i][1]
        while j < count and pairs[j][1] == value:
            j += 1
        avg_rank = (i + j - 1) * 0.5
        pct = avg_rank / denom
        score = pct if direction > 0 else 1.0 - pct
        k = i
        while k < j:
            out[pairs[k][0]] = score
            k += 1
        i = j
    return out


def _weighted_score(symbol, sleeve, rank_cache):
    total = 0.0
    present = 0.0
    for metric, spec in sleeve.items():
        weight, direction = spec
        ranks = rank_cache.get((metric, direction))
        if ranks is None:
            continue
        score = ranks.get(symbol)
        if score is None:
            continue
        total += weight * score
        present += weight
    if present <= 0.0:
        return 0.0
    return total / present


def _regime_branch(regime):
    text = ""
    bull_value = None
    breadth_value = None
    vol_value = None

    if isinstance(regime, dict):
        for key in ("name", "label", "regime", "state", "market_regime"):
            value = regime.get(key)
            if isinstance(value, str):
                text += " " + value.lower()
        bull_value = _to_float(regime.get("bull"))
        breadth_value = _to_float(regime.get("breadth"))
        vol_value = _to_float(regime.get("avg_realized_vol_3m"))
    elif isinstance(regime, str):
        text = regime.lower()

    if "bear" in text or "risk_off" in text or "defen" in text or "stress" in text:
        return "defense"
    if "bull" in text or "risk_on" in text or "uptrend" in text or "strong" in text:
        return "bull"

    if bull_value is not None and breadth_value is not None:
        if bull_value >= 0.62 and breadth_value >= 0.58:
            return "bull"
        if bull_value <= 0.45 or breadth_value <= 0.42:
            return "defense"

    if vol_value is not None and vol_value >= 0.36:
        return "defense"

    return "transition"


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


def score_universe(stocks, regime, ctx):
    rank_cache = {}
    for sleeve in (PULLBACK_REPAIR, REPAIR_LEADERSHIP, DURABLE_INCOME):
        for metric, spec in sleeve.items():
            direction = spec[1]
            key = (metric, direction)
            if key not in rank_cache:
                rank_cache[key] = _rank_map(stocks, metric, direction)

    branch = _regime_branch(regime)
    scores = {}

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

        pullback = _weighted_score(symbol, PULLBACK_REPAIR, rank_cache)
        repair = _weighted_score(symbol, REPAIR_LEADERSHIP, rank_cache)
        durable = _weighted_score(symbol, DURABLE_INCOME, rank_cache)

        d52 = _metric(stock, "from_52w_high_pct")
        d200 = _metric(stock, "from_200d_ma_pct")
        r1 = _metric(stock, "return_1m_pct")
        r3 = _metric(stock, "return_3m_pct")
        m12 = _metric(stock, "momentum_12_1_pct")
        vol = _metric(stock, "realized_vol_3m")

        shallow_pullback = d52 is not None and d52 <= -8.0 and d52 >= -28.0
        deep_pullback = d52 is not None and d52 < -28.0
        repaired = (
            (d200 is not None and d200 > -2.0) and
            ((r3 is not None and r3 > 0.0) or (m12 is not None and m12 > 0.0))
        )
        leader = (
            (d200 is not None and d200 > 4.0) and
            (m12 is not None and m12 > 0.0)
        )
        calm = vol is not None and vol < 42.0

        q_count = 0.0
        q_total = 0.0
        for metric_name in (
            "operating_margin_pct",
            "free_cash_flow_margin_pct",
            "revenue_growth_pct",
            "free_cash_flow_growth_pct",
            "forward_eps",
            "pe",
            "dividend_yield_ttm_pct",
        ):
            direction = -1 if metric_name == "pe" else +1
            rank = rank_cache.get((metric_name, direction), {}).get(symbol)
            if rank is not None:
                q_total += 1.0
                if rank > 0.55:
                    q_count += 1.0
        quality_quorum = (q_count / q_total) if q_total > 0.0 else 0.0
        quality_strong = quality_quorum >= 0.57

        liquidity = (
            rank_cache.get(("avg_daily_volume_3m", +1), {}).get(symbol, 0.5) * 0.55 +
            rank_cache.get(("trading_days_3m", +1), {}).get(symbol, 0.5) * 0.45
        )
        value_income = (
            rank_cache.get(("pe", -1), {}).get(symbol, 0.5) * 0.38 +
            rank_cache.get(("peg", -1), {}).get(symbol, 0.5) * 0.22 +
            rank_cache.get(("dividend_yield_ttm_pct", +1), {}).get(symbol, 0.5) * 0.24 +
            rank_cache.get(("dividend_ttm", +1), {}).get(symbol, 0.5) * 0.16
        )

        knife_penalty = 0.0
        if deep_pullback and not repaired and quality_quorum < 0.40:
            knife_penalty += 0.12
        if deep_pullback and d200 is not None and d200 < -10.0 and r3 is not None and r3 < 0.0:
            knife_penalty += 0.07
        if r1 is not None and r1 > 18.0 and repair < 0.50:
            knife_penalty += 0.03

        if branch == "bull":
            base = 0.45 * repair + 0.33 * pullback + 0.22 * durable
            if shallow_pullback and repaired:
                base += 0.08
            if leader and quality_quorum > 0.50:
                base += 0.05
            if deep_pullback and not repaired:
                base -= 0.10
            if pullback > repair + 0.10:
                if shallow_pullback and quality_strong:
                    base += 0.03
                else:
                    base -= 0.05
        elif branch == "transition":
            base = 0.37 * repair + 0.27 * pullback + 0.22 * durable + 0.14 * value_income
            if deep_pullback and repaired and quality_strong:
                base += 0.08
            if deep_pullback and quality_quorum < 0.45:
                base -= 0.12
            if shallow_pullback and repaired:
                base += 0.04
            if pullback > repair + 0.08:
                if quality_strong:
                    base += 0.02
                else:
                    base -= 0.06
            if repair > pullback + 0.12 and leader:
                base += 0.03
        else:
            base = 0.17 * pullback + 0.25 * repair + 0.38 * durable + 0.20 * value_income
            if repaired and calm and quality_quorum > 0.50:
                base += 0.06
            if deep_pullback and (not calm or liquidity < 0.45 or quality_quorum < 0.50):
                base -= 0.13
            if shallow_pullback and repaired and value_income > 0.55:
                base += 0.03
            if leader and durable > 0.60:
                base += 0.02

        conflict = pullback - repair
        if conflict > 0.14 and not quality_strong:
            base -= 0.05 * conflict
        elif conflict < -0.14 and leader and durable > 0.55:
            base += 0.04 * (-conflict)

        scores[symbol] = _clamp(base - knife_penalty, 0.0, 1.0)

    return scores