exp_1152

FORMULA_NAME = "Recovery Quality Contrarian 52-Week Hybrid (Relay Arbitration, v1152)"
LOGIC_VARIANT_COUNT = 3
NOTES = """mode=explore; family=recovery-quality-contrarian-52w-hybrid
This variant keeps the parent family core but changes the arbitration structure. Instead of letting one sleeve dominate by regime, it uses a relay: contrarian depth nominates candidates, repair strength confirms whether the selloff is healing, and quality plus tradability decide whether a conflict is an early turnaround or a falling knife. In bull tapes the relay prefers shallower repaired leaders off their highs; in mixed tapes it requires balanced agreement between drawdown and repair; in risk-off it only advances rebounds that also show durability, lower volatility, and reliable liquidity.
Deliberate metric coverage: active momentum metrics are return_1m_pct, return_6m_pct, momentum_12_1_pct; active trend/recovery metrics are from_52w_high_pct and from_200d_ma_pct; active volatility metric is realized_vol_3m; active liquidity metrics are avg_daily_volume_3m, avg_daily_dollar_volume_3m, trading_days_3m; active income metrics are dividend_yield_ttm_pct and dividend_ttm; active valuation metrics are forward_pe and peg; active growth metrics are operating_income_growth_pct, free_cash_flow_growth_pct, and forward_eps; active quality metrics are operating_margin_pct and free_cash_flow_margin_pct; active size metric is market_cap.
Deliberate weight-0 metrics this run: return_3m_pct, return_12m_pct, pe, 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 fields are thinned, raw level fields stay off, and sparse fundamentals are normalized by present weight so missing data does not automatically zero a stock.
"""

_DIRECTION = {
    "return_1m_pct": -1,
    "return_6m_pct": 1,
    "momentum_12_1_pct": 1,
    "from_52w_high_pct": -1,
    "from_200d_ma_pct": 1,
    "realized_vol_3m": -1,
    "avg_daily_volume_3m": 1,
    "avg_daily_dollar_volume_3m": 1,
    "trading_days_3m": 1,
    "dividend_yield_ttm_pct": 1,
    "dividend_ttm": 1,
    "forward_pe": -1,
    "peg": -1,
    "operating_income_growth_pct": 1,
    "free_cash_flow_growth_pct": 1,
    "forward_eps": 1,
    "operating_margin_pct": 1,
    "free_cash_flow_margin_pct": 1,
    "market_cap": -1,
}


def _to_number(value):
    if value is None or value is False or value is True:
        return None
    try:
        number = float(value)
    except Exception:
        return None
    if number != number:
        return None
    return number


def _get_symbol(stock):
    for key in ("symbol", "ticker", "name"):
        value = stock.get(key)
        if value:
            return str(value)
    return None


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


def _percentile_ranks(stocks, metric, direction):
    pairs = []
    for stock in stocks:
        symbol = _get_symbol(stock)
        if not symbol:
            continue
        value = _to_number(stock.get(metric))
        if value is None:
            continue
        pairs.append((symbol, value * direction))

    ranks = {}
    count = len(pairs)
    if count == 0:
        return ranks

    pairs.sort(key=lambda item: item[1])
    if count == 1:
        ranks[pairs[0][0]] = 1.0
        return ranks

    index = 0
    while index < count:
        end = index
        current = pairs[index][1]
        while end + 1 < count and pairs[end + 1][1] == current:
            end += 1
        rank = ((index + end) * 0.5) / (count - 1.0)
        while index <= end:
            ranks[pairs[index][0]] = rank
            index += 1
    return ranks


def _weighted_score(symbol, rank_map, weights, neutral=0.5):
    total = 0.0
    used = 0.0
    for metric, weight in weights.items():
        metric_ranks = rank_map.get(metric, {})
        if symbol not in metric_ranks:
            continue
        total += metric_ranks[symbol] * weight
        used += weight
    if used <= 0.0:
        return neutral
    return total / used


def _regime_branch(regime, ctx):
    text = ""
    if regime is not None:
        text += str(regime).lower() + " "
    if ctx is not None:
        regime_hint = ctx.get("regime") if isinstance(ctx, dict) else None
        if regime_hint is not None:
            text += str(regime_hint).lower() + " "

    if (
        "risk_off" in text
        or "risk-off" in text
        or "bear" in text
        or "defensive" in text
        or "drawdown" in text
        or "panic" in text
    ):
        return "risk_off"
    if (
        "bull" in text
        or "risk_on" in text
        or "risk-on" in text
        or "uptrend" in text
        or "strong" in text
    ):
        return "bull"
    return "transition"


def score_universe(stocks, regime, ctx):
    rank_map = {}
    for metric, direction in _DIRECTION.items():
        rank_map[metric] = _percentile_ranks(stocks, metric, direction)

    contrarian_weights = {
        "from_52w_high_pct": 0.44,
        "return_1m_pct": 0.16,
        "forward_pe": 0.12,
        "peg": 0.12,
        "market_cap": 0.16,
    }
    repair_weights = {
        "from_200d_ma_pct": 0.30,
        "return_6m_pct": 0.24,
        "momentum_12_1_pct": 0.18,
        "operating_income_growth_pct": 0.16,
        "forward_eps": 0.12,
    }
    durability_weights = {
        "realized_vol_3m": 0.22,
        "operating_margin_pct": 0.24,
        "free_cash_flow_margin_pct": 0.20,
        "dividend_yield_ttm_pct": 0.18,
        "dividend_ttm": 0.16,
    }
    liquidity_weights = {
        "avg_daily_dollar_volume_3m": 0.46,
        "avg_daily_volume_3m": 0.28,
        "trading_days_3m": 0.26,
    }
    growth_value_weights = {
        "operating_income_growth_pct": 0.28,
        "free_cash_flow_growth_pct": 0.24,
        "forward_eps": 0.16,
        "forward_pe": 0.18,
        "peg": 0.14,
    }

    branch = _regime_branch(regime, ctx)
    scores = {}

    for stock in stocks:
        symbol = _get_symbol(stock)
        if not symbol:
            continue

        contrarian = _weighted_score(symbol, rank_map, contrarian_weights)
        repair = _weighted_score(symbol, rank_map, repair_weights)
        durability = _weighted_score(symbol, rank_map, durability_weights)
        liquidity = _weighted_score(symbol, rank_map, liquidity_weights)
        growth_value = _weighted_score(symbol, rank_map, growth_value_weights)

        disagreement = abs(contrarian - repair)
        knife_risk = contrarian * (1.0 - repair) * (1.0 - durability)
        balanced_relay = contrarian if contrarian < repair else repair
        conflict_penalty = disagreement * (1.0 - durability)

        shallow_repair_sweet_spot = 1.0 - abs(contrarian - 0.64) / 0.64
        shallow_repair_sweet_spot = _clip(shallow_repair_sweet_spot, 0.0, 1.0)

        if branch == "bull":
            base = (
                0.34 * repair
                + 0.24 * shallow_repair_sweet_spot
                + 0.16 * growth_value
                + 0.14 * durability
                + 0.12 * liquidity
            )
            multiplier = 0.82 + 0.26 * durability + 0.12 * liquidity
            score = base * multiplier - 0.16 * knife_risk - 0.06 * conflict_penalty
        elif branch == "risk_off":
            defensive_turn = contrarian * (0.58 * durability + 0.42 * repair)
            base = (
                0.34 * durability
                + 0.20 * repair
                + 0.18 * defensive_turn
                + 0.16 * liquidity
                + 0.12 * growth_value
            )
            multiplier = 0.76 + 0.28 * liquidity + 0.18 * durability
            score = base * multiplier - 0.22 * knife_risk - 0.08 * disagreement
        else:
            base = (
                0.32 * balanced_relay
                + 0.24 * durability
                + 0.16 * growth_value
                + 0.14 * liquidity
                + 0.14 * contrarian
            )
            multiplier = 0.78 + 0.30 * durability + 0.10 * repair
            score = base * multiplier - 0.10 * conflict_penalty - 0.12 * knife_risk

        scores[symbol] = score

    return scores