exp_1188

FORMULA_NAME = "Contrarian 52W Recovery Quality Hybrid (Conflict-Arbitrated Relay, v1188)"
LOGIC_VARIANT_COUNT = 3
NOTES = """mode=explore; family=contrarian-52w-recovery-quality-hybrid
New hybrid family built by combining the bull recovery-leader contrarian sweet-spot from contrarian-52w with the stock-level conflict arbitration and quality/liquidity discipline from recovery-quality-regime-momentum-hybrid. The structure is intentionally not a mechanical average: in bull tapes, repaired rebounders can graduate into momentum only after quality confirms; in mixed tapes, recovery only gets paid when liquidity and balance-sheet proxies are good enough; in risk-off, the model falls back to lower-volatility durable franchises entered from modest 52-week drawdowns rather than deep damage.
Deliberate metric coverage: actively use one momentum cluster (3m, 6m, 12_1), one recovery cluster (distance from 52-week high plus 200d trend), one volatility check, all three liquidity checks in mixed/risk-off, one income metric, two valuation metrics, three growth/earnings proxies, two quality metrics, and a size tilt that flips by regime. Deliberate weight-0 metrics this run: return_1m_pct, return_12m_pct, dividend_ttm, 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."""

# Deliberate weight-0 metrics this run:
# - Momentum/return: return_1m_pct, return_12m_pct
# - Income: dividend_ttm
# - Valuation: pe
# - Growth/raw fundamentals: 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

USED_METRICS = (
    "from_52w_high_pct",
    "from_200d_ma_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",
    "forward_pe",
    "peg",
    "forward_eps",
    "operating_income_growth_pct",
    "free_cash_flow_growth_pct",
    "free_cash_flow_margin_pct",
    "operating_margin_pct",
    "market_cap",
)


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


def _to_float(x):
    if x is None:
        return None
    if isinstance(x, bool):
        return 1.0 if x else 0.0
    if isinstance(x, (int, float)):
        return float(x)
    try:
        return float(x)
    except Exception:
        return None


def _normalize_metric(metric, value):
    x = _to_float(value)
    if x is None:
        return None

    if metric == "from_52w_high_pct":
        if x < 0.0:
            x = -x
        if x > 1.5:
            x /= 100.0
        return x

    if metric in (
        "from_200d_ma_pct",
        "return_3m_pct",
        "return_6m_pct",
        "momentum_12_1_pct",
        "dividend_yield_ttm_pct",
        "operating_income_growth_pct",
        "free_cash_flow_growth_pct",
        "free_cash_flow_margin_pct",
        "operating_margin_pct",
    ):
        if x > 1.5 or x < -1.5:
            x /= 100.0
        return x

    if metric == "realized_vol_3m":
        if x > 3.0:
            x /= 100.0
        return x

    return x


def _metric_value(stock, metric):
    return _normalize_metric(metric, stock.get(metric))


def _rank_map(value_map, higher_is_better):
    items = sorted(value_map.items(), key=lambda kv: kv[1])
    n = len(items)
    if n == 0:
        return {}
    if n == 1:
        return {items[0][0]: 0.5}

    out = {}
    i = 0
    while i < n:
        j = i
        v = items[i][1]
        while j + 1 < n and items[j + 1][1] == v:
            j += 1
        pct = ((i + j) * 0.5) / float(n - 1)
        score = pct if higher_is_better else (1.0 - pct)
        k = i
        while k <= j:
            out[items[k][0]] = score
            k += 1
        i = j + 1
    return out


def _get_score(score_map, symbol, default=0.5):
    v = score_map.get(symbol)
    if v is None:
        return default
    return v


def _avg(values):
    total = 0.0
    count = 0
    for v in values:
        if v is not None:
            total += v
            count += 1
    if count == 0:
        return 0.5
    return total / float(count)


def _sweet_spot(value, low, high, center):
    if value is None:
        return 0.5
    if value <= low or value >= high:
        return 0.0
    if value == center:
        return 1.0
    if value < center:
        denom = center - low
        if denom <= 0:
            return 0.0
        return _clamp((value - low) / denom, 0.0, 1.0)
    denom = high - center
    if denom <= 0:
        return 0.0
    return _clamp((high - value) / denom, 0.0, 1.0)


def _detect_branch(regime):
    text = ""
    if isinstance(regime, str):
        text = regime.lower()
    elif isinstance(regime, dict):
        parts = []
        for key in (
            "regime",
            "name",
            "market_regime",
            "state",
            "trend",
            "risk_regime",
            "volatility_regime",
        ):
            if key in regime and regime.get(key) is not None:
                parts.append(str(regime.get(key)).lower())
        text = " ".join(parts)

        for key in ("risk_off", "defensive", "bearish", "crisis"):
            val = regime.get(key)
            if val is True:
                return "risk_off"
        for key in ("bull", "bullish", "risk_on"):
            val = regime.get(key)
            if val is True:
                return "bull"

    if (
        "risk_off" in text
        or "bear" in text
        or "defensive" in text
        or "crash" in text
        or "stress" in text
        or "high_vol" in text
        or "panic" in text
    ):
        return "risk_off"

    if (
        "bull" in text
        or "risk_on" in text
        or "uptrend" in text
        or "strong" in text
        or "momentum" in text
        or "breakout" in text
    ):
        return "bull"

    return "mixed"


def score_universe(stocks, regime, ctx):
    symbols = []
    metric_maps = {}
    for metric in USED_METRICS:
        metric_maps[metric] = {}

    for stock in stocks:
        symbol = stock.get("symbol")
        if not symbol:
            continue
        symbols.append(symbol)
        for metric in USED_METRICS:
            val = _metric_value(stock, metric)
            if val is not None:
                metric_maps[metric][symbol] = val

    ranks = {
        "from_200d_ma_pct": _rank_map(metric_maps["from_200d_ma_pct"], True),
        "return_3m_pct": _rank_map(metric_maps["return_3m_pct"], True),
        "return_6m_pct": _rank_map(metric_maps["return_6m_pct"], True),
        "momentum_12_1_pct": _rank_map(metric_maps["momentum_12_1_pct"], True),
        "realized_vol_3m": _rank_map(metric_maps["realized_vol_3m"], False),
        "avg_daily_volume_3m": _rank_map(metric_maps["avg_daily_volume_3m"], True),
        "avg_daily_dollar_volume_3m": _rank_map(metric_maps["avg_daily_dollar_volume_3m"], True),
        "trading_days_3m": _rank_map(metric_maps["trading_days_3m"], True),
        "dividend_yield_ttm_pct": _rank_map(metric_maps["dividend_yield_ttm_pct"], True),
        "forward_pe": _rank_map(metric_maps["forward_pe"], False),
        "peg": _rank_map(metric_maps["peg"], False),
        "forward_eps": _rank_map(metric_maps["forward_eps"], True),
        "operating_income_growth_pct": _rank_map(metric_maps["operating_income_growth_pct"], True),
        "free_cash_flow_growth_pct": _rank_map(metric_maps["free_cash_flow_growth_pct"], True),
        "free_cash_flow_margin_pct": _rank_map(metric_maps["free_cash_flow_margin_pct"], True),
        "operating_margin_pct": _rank_map(metric_maps["operating_margin_pct"], True),
        "market_cap_small": _rank_map(metric_maps["market_cap"], False),
        "market_cap_large": _rank_map(metric_maps["market_cap"], True),
    }

    branch = _detect_branch(regime)
    out = {}

    for symbol in symbols:
        dd_raw = metric_maps["from_52w_high_pct"].get(symbol)
        dd_bull = _sweet_spot(dd_raw, 0.08, 0.30, 0.17)
        dd_mixed = _sweet_spot(dd_raw, 0.14, 0.42, 0.26)
        dd_def = _sweet_spot(dd_raw, 0.06, 0.24, 0.14)

        trend = _get_score(ranks["from_200d_ma_pct"], symbol)
        r3 = _get_score(ranks["return_3m_pct"], symbol)
        r6 = _get_score(ranks["return_6m_pct"], symbol)
        m12 = _get_score(ranks["momentum_12_1_pct"], symbol)
        low_vol = _get_score(ranks["realized_vol_3m"], symbol)

        liq_volume = _get_score(ranks["avg_daily_volume_3m"], symbol)
        liq_dollar = _get_score(ranks["avg_daily_dollar_volume_3m"], symbol)
        liq_days = _get_score(ranks["trading_days_3m"], symbol)
        liquidity = _avg((liq_volume, liq_dollar, liq_days))

        div_yield = _get_score(ranks["dividend_yield_ttm_pct"], symbol)
        cheap_pe = _get_score(ranks["forward_pe"], symbol)
        cheap_peg = _get_score(ranks["peg"], symbol)
        valuation = _avg((cheap_pe, cheap_peg))

        fwd_eps = _get_score(ranks["forward_eps"], symbol)
        op_growth = _get_score(ranks["operating_income_growth_pct"], symbol)
        fcf_growth = _get_score(ranks["free_cash_flow_growth_pct"], symbol)
        growth = _avg((fwd_eps, op_growth, fcf_growth))

        fcf_margin = _get_score(ranks["free_cash_flow_margin_pct"], symbol)
        op_margin = _get_score(ranks["operating_margin_pct"], symbol)
        quality = _avg((fcf_margin, op_margin))

        small_cap = _get_score(ranks["market_cap_small"], symbol)
        large_cap = _get_score(ranks["market_cap_large"], symbol)

        if branch == "bull":
            recovery_core = (
                0.28 * dd_bull
                + 0.18 * trend
                + 0.12 * r6
                + 0.08 * low_vol
                + 0.06 * div_yield
                + 0.08 * small_cap
                + 0.10 * fcf_margin
                + 0.10 * op_margin
            )
            graduate_momentum = (
                0.24 * m12
                + 0.16 * r3
                + 0.16 * r6
                + 0.10 * trend
                + 0.10 * dd_bull
                + 0.12 * fwd_eps
                + 0.12 * fcf_margin
            )
            quality_gate = 0.45 * quality + 0.30 * low_vol + 0.25 * liquidity
            relay = _clamp((m12 + r6 + trend + dd_bull - 1.90) / 1.40, 0.0, 1.0)
            relay *= _clamp((quality_gate - 0.45) / 0.40, 0.0, 1.0)
            score = (1.0 - 0.55 * relay) * recovery_core + (0.55 * relay) * graduate_momentum

        elif branch == "risk_off":
            durable_franchise = (
                0.18 * dd_def
                + 0.14 * trend
                + 0.18 * low_vol
                + 0.12 * liquidity
                + 0.12 * quality
                + 0.10 * valuation
                + 0.08 * div_yield
                + 0.06 * growth
                + 0.10 * large_cap
            )
            damage_penalty = _clamp((0.35 - dd_def) / 0.35, 0.0, 1.0) * _clamp((0.45 - trend) / 0.45, 0.0, 1.0)
            score = durable_franchise - 0.10 * damage_penalty

        else:
            repaired_rebound = (
                0.26 * dd_mixed
                + 0.18 * trend
                + 0.10 * r6
                + 0.12 * quality
                + 0.12 * liquidity
                + 0.08 * valuation
                + 0.08 * growth
                + 0.06 * low_vol
            )
            chase_sleeve = (
                0.22 * m12
                + 0.14 * r3
                + 0.12 * trend
                + 0.08 * quality
                + 0.08 * liquidity
                + 0.06 * valuation
            )
            gate = 0.40 * quality + 0.30 * liquidity + 0.20 * low_vol + 0.10 * valuation
            chase_weight = _clamp((m12 + trend - dd_mixed - 0.35) / 0.80, 0.0, 1.0)
            chase_weight *= _clamp((gate - 0.45) / 0.45, 0.0, 1.0)
            base = (1.0 - 0.35 * chase_weight) * repaired_rebound + (0.35 * chase_weight) * chase_sleeve
            conflict_penalty = _clamp((0.52 - gate) / 0.52, 0.0, 1.0) * _clamp((m12 - dd_mixed + 0.10) / 0.55, 0.0, 1.0)
            repair_bonus = _clamp((dd_mixed + trend + gate - 1.55) / 0.65, 0.0, 1.0)
            score = base - 0.12 * conflict_penalty + 0.06 * repair_bonus

        out[symbol] = score

    return out