exp_1119

FORMULA_NAME = "Recovery Quality Regime Momentum Fundamental Hybrid (Explore, v1119)"
LOGIC_VARIANT_COUNT = 3
NOTES = """mode=explore; family=recovery-quality-regime-momentum-fundamental-mom-hybrid
This hybrid keeps three distinct jobs instead of one blended average: a trend-following bull branch, a repaired-rebound recovery branch, and a low-volatility defensive branch. The arbitration mechanism is explicit: each branch changes which evidence can dominate, and branch-specific conflict haircuts prevent pure price strength from outranking weak fundamentals or low-quality rebounds.
Deliberate metric coverage: momentum uses return_1m_pct, return_3m_pct, return_6m_pct, and momentum_12_1_pct across branches; 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 in defense only; valuation uses forward_pe and peg; growth uses eps_growth_pct, revenue_growth_pct, operating_income_growth_pct, and free_cash_flow_growth_pct; quality uses operating_margin_pct and free_cash_flow_margin_pct; size uses shares_outstanding as a light small-cap tilt only in recovery. Raw level metrics are deliberately zero-weighted this run to avoid collapsing into another large-cap fundamental screen.
Deliberate weight-0 metrics this run: return_12m_pct, pe, forward_eps, dividend_ttm, close, adj_close, high_52w, ma_200d, eps_ttm, revenue_ttm, operating_income_ttm, free_cash_flow_ttm."""

BULL = {
    "momentum_12_1_pct": (0.20, +1),
    "return_6m_pct": (0.17, +1),
    "from_200d_ma_pct": (0.10, +1),
    "avg_daily_dollar_volume_3m": (0.07, +1),
    "trading_days_3m": (0.05, +1),
    "eps_growth_pct": (0.10, +1),
    "operating_income_growth_pct": (0.11, +1),
    "free_cash_flow_margin_pct": (0.11, +1),
    "forward_pe": (0.06, -1),
    "realized_vol_3m": (0.03, -1),
}

RECOVERY = {
    "return_1m_pct": (0.10, +1),
    "return_3m_pct": (0.16, +1),
    "from_200d_ma_pct": (0.18, +1),
    "from_52w_high_pct": (0.14, +1),
    "momentum_12_1_pct": (0.08, +1),
    "avg_daily_volume_3m": (0.05, +1),
    "avg_daily_dollar_volume_3m": (0.05, +1),
    "operating_margin_pct": (0.08, +1),
    "free_cash_flow_growth_pct": (0.07, +1),
    "peg": (0.05, -1),
    "shares_outstanding": (0.04, -1),
}

DEFENSE = {
    "realized_vol_3m": (0.18, -1),
    "from_200d_ma_pct": (0.14, +1),
    "from_52w_high_pct": (0.10, +1),
    "momentum_12_1_pct": (0.08, +1),
    "trading_days_3m": (0.07, +1),
    "dividend_yield_ttm_pct": (0.06, +1),
    "revenue_growth_pct": (0.08, +1),
    "operating_margin_pct": (0.11, +1),
    "free_cash_flow_margin_pct": (0.08, +1),
    "forward_pe": (0.05, -1),
    "peg": (0.05, -1),
}

def _safe_float(value):
    if value is None:
        return None
    try:
        value = float(value)
    except (TypeError, ValueError):
        return None
    if value != value:
        return None
    return value

def _get_field(obj, key):
    if isinstance(obj, dict):
        return obj.get(key)
    return getattr(obj, key, None)

def _symbol(stock):
    sym = _get_field(stock, "symbol")
    if sym is None:
        sym = _get_field(stock, "ticker")
    return sym

def _rank_metric(stocks, metric, higher_is_better):
    values = []
    for stock in stocks:
        sym = _symbol(stock)
        if not sym:
            continue
        val = _safe_float(_get_field(stock, metric))
        if val is None:
            continue
        values.append((sym, val))
    ranks = {}
    if not values:
        for stock in stocks:
            sym = _symbol(stock)
            if sym:
                ranks[sym] = 0.5
        return ranks
    values.sort(key=lambda item: item[1], reverse=higher_is_better)
    count = len(values)
    if count == 1:
        ranks[values[0][0]] = 1.0
    else:
        for idx, (sym, _) in enumerate(values):
            ranks[sym] = idx / float(count - 1)
            if higher_is_better:
                ranks[sym] = 1.0 - ranks[sym]
    for stock in stocks:
        sym = _symbol(stock)
        if sym and sym not in ranks:
            ranks[sym] = 0.5
    return ranks

def _weighted_score(symbol, metric_defs, cache):
    total = 0.0
    weight_sum = 0.0
    for metric, (weight, direction) in metric_defs.items():
        total += weight * cache[(metric, direction)].get(symbol, 0.5)
        weight_sum += weight
    if weight_sum <= 0.0:
        return 0.0
    return total / weight_sum

def _avg_score(symbol, cache, metric_pairs):
    total = 0.0
    count = 0
    for metric, direction in metric_pairs:
        total += cache[(metric, direction)].get(symbol, 0.5)
        count += 1
    if count == 0:
        return 0.5
    return total / float(count)

def _regime_text(regime):
    parts = []
    if isinstance(regime, str):
        return regime.lower()
    for key in ("regime", "state", "name", "label", "market_regime", "phase"):
        value = _get_field(regime, key)
        if isinstance(value, str):
            parts.append(value.lower())
    return " ".join(parts)

def _regime_value(regime, key):
    return _safe_float(_get_field(regime, key))

def _pick_branch(regime):
    text = _regime_text(regime)
    if any(token in text for token in ("risk_off", "risk-off", "defensive", "defense", "bear", "stress", "crash", "panic")):
        return "defense"
    if any(token in text for token in ("recovery", "rebound", "repair", "mean_reversion", "mean-reversion")):
        return "recovery"
    if any(token in text for token in ("bull", "risk_on", "risk-on", "trend", "expansion")):
        return "bull"

    risk_off = 0.0
    recovery = 0.0
    for key in ("risk_off_prob", "bear_prob", "stress_prob", "defensive_prob"):
        value = _regime_value(regime, key)
        if value is not None and value > risk_off:
            risk_off = value
    for key in ("recovery_prob", "rebound_prob", "repair_prob"):
        value = _regime_value(regime, key)
        if value is not None and value > recovery:
            recovery = value

    if risk_off >= 0.55:
        return "defense"
    if recovery >= 0.50:
        return "recovery"
    return "bull"

def score_universe(stocks, regime, ctx):
    branch = _pick_branch(regime)

    metric_defs = {}
    for defs in (BULL, RECOVERY, DEFENSE):
        for metric, (_, direction) in defs.items():
            metric_defs[(metric, direction)] = True

    cache = {}
    for metric, direction in metric_defs:
        cache[(metric, direction)] = _rank_metric(stocks, metric, direction > 0)

    scores = {}
    for stock in stocks:
        sym = _symbol(stock)
        if not sym:
            continue

        momentum = _avg_score(sym, cache, [
            ("return_1m_pct", +1),
            ("return_3m_pct", +1),
            ("return_6m_pct", +1),
            ("momentum_12_1_pct", +1),
        ])
        recovery = _avg_score(sym, cache, [
            ("return_1m_pct", +1),
            ("return_3m_pct", +1),
            ("from_200d_ma_pct", +1),
            ("from_52w_high_pct", +1),
        ])
        growth = _avg_score(sym, cache, [
            ("eps_growth_pct", +1),
            ("revenue_growth_pct", +1),
            ("operating_income_growth_pct", +1),
            ("free_cash_flow_growth_pct", +1),
        ])
        quality = _avg_score(sym, cache, [
            ("operating_margin_pct", +1),
            ("free_cash_flow_margin_pct", +1),
        ])
        value = _avg_score(sym, cache, [
            ("forward_pe", -1),
            ("peg", -1),
        ])
        liquidity = _avg_score(sym, cache, [
            ("avg_daily_volume_3m", +1),
            ("avg_daily_dollar_volume_3m", +1),
            ("trading_days_3m", +1),
        ])
        stability = _avg_score(sym, cache, [
            ("realized_vol_3m", -1),
            ("from_200d_ma_pct", +1),
            ("from_52w_high_pct", +1),
        ])
        income = _avg_score(sym, cache, [
            ("dividend_yield_ttm_pct", +1),
        ])
        size = _avg_score(sym, cache, [
            ("shares_outstanding", -1),
        ])

        if branch == "bull":
            base = _weighted_score(sym, BULL, cache)
            fundamental_confirm = 0.45 * growth + 0.35 * quality + 0.20 * value
            implementation = 0.65 * liquidity + 0.35 * stability
            conflict = 0.0
            if momentum > 0.68 and fundamental_confirm < 0.46:
                conflict -= 0.12 * (0.46 - fundamental_confirm)
            if fundamental_confirm > 0.66 and momentum < 0.42:
                conflict -= 0.08 * (0.42 - momentum)
            score = 0.48 * base + 0.24 * momentum + 0.18 * fundamental_confirm + 0.10 * implementation + conflict
        elif branch == "recovery":
            base = _weighted_score(sym, RECOVERY, cache)
            repaired_rebound = 0.60 * recovery + 0.25 * momentum + 0.15 * stability
            durable_confirm = 0.40 * quality + 0.30 * growth + 0.15 * value + 0.15 * liquidity
            conflict = 0.0
            if repaired_rebound > 0.65 and durable_confirm < 0.44:
                conflict -= 0.14 * (0.44 - durable_confirm)
            if durable_confirm > 0.64 and repaired_rebound < 0.43:
                conflict -= 0.10 * (0.43 - repaired_rebound)
            score = 0.44 * base + 0.30 * repaired_rebound + 0.18 * durable_confirm + 0.08 * size + conflict
        else:
            base = _weighted_score(sym, DEFENSE, cache)
            resilience = 0.40 * stability + 0.25 * quality + 0.20 * value + 0.15 * liquidity
            carry = 0.55 * income + 0.45 * growth
            conflict = 0.0
            if momentum > 0.70 and stability < 0.45:
                conflict -= 0.12 * (0.45 - stability)
            if value > 0.68 and growth < 0.38:
                conflict -= 0.08 * (0.38 - growth)
            score = 0.46 * base + 0.28 * resilience + 0.14 * carry + 0.12 * momentum + conflict

        scores[sym] = score

    return scores