aether-quant 0.0.1__py3-none-any.whl

features/derivatives_macro_features.py

@@ -0,0 +1,72 @@
+"""Shared, pure futures-term-structure / options-sentiment "macro" feature
+implementations - additive third sibling to features/macro_features.py and
+features/bond_features.py, broadcast identically to EVERY asset's model
+input (not just futures/options assets themselves).
+
+This is the concrete mechanism satisfying the "the model's cross-asset
+macro features should include options/futures/bond-derived signals so any
+asset's prediction can be informed by them" requirement - generalized well
+beyond any single hardcoded pair (e.g. "predict SPY from QQQ options" was
+only ever an illustrative example, not a special case to hardcode).
+
+Every function neutral-defaults to 0.0 on missing input - never raises -
+same convention as features/macro_features.py. Since real futures
+continuous-contract prices and options chain volumes only exist once IB is
+connected (phase_v2.ib.enabled), these features are 0.0 for every asset,
+every date, until then - a correctness property, not a bug: "no derivatives
+data configured" must be indistinguishable in the model input from "the
+signal happens to be neutral today," matching every other missing-
+reference-ticker case in this codebase.
+"""
+
+from __future__ import annotations
+
+FUTURES_TERM_STRUCTURE_SLOPE_NEUTRAL = 0.0
+OPTIONS_PUT_CALL_RATIO_NEUTRAL = 0.0
+OPTIONS_IMPLIED_VOL_SKEW_NEUTRAL = 0.0
+
+FUTURES_MACRO_FEATURE_NAMES = ["futures_term_structure_slope"]
+OPTIONS_MACRO_FEATURE_NAMES = ["options_put_call_ratio", "options_implied_vol_skew"]
+DERIVATIVES_MACRO_FEATURE_NAMES = FUTURES_MACRO_FEATURE_NAMES + OPTIONS_MACRO_FEATURE_NAMES
+
+
+def futures_term_structure_slope(front_month_price: float | None, next_month_price: float | None) -> float:
+    """(next_month - front_month) / front_month - positive = contango
+    (next-month more expensive, typical/"normal" market), negative =
+    backwardation (front-month more expensive, often a supply-stress or
+    high-carry-cost signal). Returns
+    FUTURES_TERM_STRUCTURE_SLOPE_NEUTRAL (0.0) when either input is
+    missing or front_month_price is zero."""
+    if front_month_price is None or next_month_price is None or front_month_price == 0:
+        return FUTURES_TERM_STRUCTURE_SLOPE_NEUTRAL
+    return (next_month_price - front_month_price) / front_month_price
+
+
+def options_put_call_ratio(put_volume: float | None, call_volume: float | None) -> float:
+    """A bounded [-1, 1] put/call VOLUME skew - (put - call) / (put +
+    call), not the raw put/call ratio - chosen specifically so 0.0 is a
+    genuinely meaningful neutral value (balanced put/call activity OR no
+    chain data available, both correctly represented as "no signal"),
+    unlike a raw ratio where 0.0 would ambiguously also mean "zero puts,
+    some calls" (a real, non-neutral market state). Positive = put-heavy
+    (bearish/hedging-heavy sentiment), negative = call-heavy (bullish
+    sentiment). Returns OPTIONS_PUT_CALL_RATIO_NEUTRAL (0.0) when either
+    input is missing or both volumes are zero."""
+    if put_volume is None or call_volume is None:
+        return OPTIONS_PUT_CALL_RATIO_NEUTRAL
+    total_volume = put_volume + call_volume
+    if total_volume <= 0:
+        return OPTIONS_PUT_CALL_RATIO_NEUTRAL
+    return (put_volume - call_volume) / total_volume
+
+
+def options_implied_vol_skew(otm_put_iv: float | None, otm_call_iv: float | None) -> float:
+    """OTM put implied vol minus OTM call implied vol (both at a matched
+    delta, e.g. 25-delta each, per features/options_greeks.py's
+    implied_volatility()) - the standard equity-index "smirk" measure;
+    positive (the typical case) means downside protection carries a
+    volatility premium over upside calls. Returns
+    OPTIONS_IMPLIED_VOL_SKEW_NEUTRAL (0.0) when either input is missing."""
+    if otm_put_iv is None or otm_call_iv is None:
+        return OPTIONS_IMPLIED_VOL_SKEW_NEUTRAL
+    return otm_put_iv - otm_call_iv

features/macro_features.py

@@ -0,0 +1,79 @@
+"""Shared, pure cross-asset "macro" feature implementations (Phase 1b of
+the 5/10 -> 9/10 roadmap, see development/Changelog.md) - deliberate,
+explicit signals computed once per bar/date from a small set of fixed
+reference tickers (the Phase 1a bond ETF sleeve + the existing crypto
+sleeve) and broadcast identically to every asset's model input that
+bar/date, mirroring how regime state is already a shared, once-per-bar
+feature.
+
+This is distinct from - and additive to - the existing generic
+correlation-based peer mechanism (topology/market_topology.py's
+top_peers/top_peer_returns): that mechanism already lets a bond or crypto
+asset surface as an equity's correlated peer purely incidentally, with no
+code change needed. These functions instead compute a small, fixed,
+always-present macro state (yield-curve slope, credit spread, crypto risk
+appetite) that every asset sees identically regardless of whether it
+happens to correlate with any one specific reference ticker that day.
+
+Imported by BOTH train.py (offline, per-date lookup across the whole
+universe) and main.py (runtime, once per bar) for parity by construction -
+same convention as features/technical_indicators.py.
+
+Each function takes plain optional-float 20-day-momentum inputs (reusing
+the existing momentum_20d column/computation already produced by
+train.py::engineer_features()/main.py's topology-payload step, rather than
+re-deriving returns from scratch) and returns a single scalar float. A
+missing/unavailable reference ticker (still warming up, or absent from
+this particular universe configuration) neutral-defaults its proxy to 0.0
+- never raises - same "missing peer -> 0.0" convention peer-return
+features already established.
+"""
+
+from __future__ import annotations
+
+YIELD_CURVE_SLOPE_NEUTRAL = 0.0
+CREDIT_SPREAD_NEUTRAL = 0.0
+CRYPTO_RISK_APPETITE_NEUTRAL = 0.0
+
+
+def yield_curve_slope_proxy(
+    long_duration_momentum_20d: float | None,
+    short_duration_momentum_20d: float | None,
+) -> float:
+    """Relative 20-day momentum spread between a long-duration Treasury
+    ETF (e.g. TLT) and a short-duration one (e.g. SHY) - a proxy for
+    curve-steepening (positive: long duration outperforming, typically
+    falling long yields relative to short) vs. flattening/inverting
+    (negative) sentiment, computable from price data alone with no
+    separate yield-level data feed. Returns YIELD_CURVE_SLOPE_NEUTRAL (0.0)
+    when either input is unavailable (reference ticker missing or still
+    warming up)."""
+    if long_duration_momentum_20d is None or short_duration_momentum_20d is None:
+        return YIELD_CURVE_SLOPE_NEUTRAL
+    return long_duration_momentum_20d - short_duration_momentum_20d
+
+
+def credit_spread_proxy(
+    high_yield_momentum_20d: float | None,
+    investment_grade_momentum_20d: float | None,
+) -> float:
+    """Relative 20-day momentum spread between a high-yield corporate bond
+    ETF (e.g. HYG) and an investment-grade one (e.g. LQD) - widens
+    (negative: high-yield underperforming investment-grade) when credit
+    risk appetite deteriorates, a standard risk-off signal. Returns
+    CREDIT_SPREAD_NEUTRAL (0.0) when either input is unavailable."""
+    if high_yield_momentum_20d is None or investment_grade_momentum_20d is None:
+        return CREDIT_SPREAD_NEUTRAL
+    return high_yield_momentum_20d - investment_grade_momentum_20d
+
+
+def crypto_risk_appetite_proxy(crypto_momentum_20d: float | None) -> float:
+    """20-day momentum of a liquid crypto reference asset (e.g. BTCUSD) -
+    a fast-moving risk-on/risk-off signal distinct from the slower-moving
+    bond-based proxies above, given crypto's comparatively higher
+    volatility and shorter mean-reversion cycles. Returns
+    CRYPTO_RISK_APPETITE_NEUTRAL (0.0) when the reference asset's momentum
+    is unavailable."""
+    if crypto_momentum_20d is None:
+        return CRYPTO_RISK_APPETITE_NEUTRAL
+    return crypto_momentum_20d

features/options_greeks.py

@@ -0,0 +1,329 @@
+"""Pure Black-Scholes-Merton option pricing/greeks/implied-volatility - the
+real-math foundation for greeks-aware options position sizing
+(portfolio/options_strategy.py), per the user's explicit requirement: real
+Black-Scholes greeks/IV computed from actual option chain data (when IB is
+enabled), not proxies.
+
+Stdlib only (math.erf for the normal CDF - no scipy dependency), same
+"pure function, no I/O" convention as features/bond_features.py and
+features/macro_features.py. Every function is a straight textbook
+implementation, unit-tested against known closed-form values
+(tests/test_options_greeks.py) and the put-call parity invariant.
+
+`right` is always "call" or "put" (case-insensitive), matching the
+vocabulary portfolio/options_strategy.py's chain rows use.
+
+V4.7 (development/Problems.md - early-assignment/corporate-action
+modeling) added baw_american_price(), a Barone-Adesi-Whaley American-
+exercise approximation built entirely from this module's own European
+bs_price()/_d1_d2()/_normal_cdf() - see its own docstring for the
+degrade-to-European safety contract. Everything above it in this file
+remains pure European BSM, unchanged.
+"""
+
+from __future__ import annotations
+
+import math
+
+_SQRT_2PI = math.sqrt(2.0 * math.pi)
+
+
+def _normal_pdf(x: float) -> float:
+    return math.exp(-0.5 * x * x) / _SQRT_2PI
+
+
+def _normal_cdf(x: float) -> float:
+    return 0.5 * (1.0 + math.erf(x / math.sqrt(2.0)))
+
+
+def _d1_d2(spot: float, strike: float, time_to_expiry_years: float, risk_free_rate: float, volatility: float, dividend_yield: float) -> tuple[float, float]:
+    variance_term = volatility * math.sqrt(time_to_expiry_years)
+    d1 = (
+        math.log(spot / strike) + (risk_free_rate - dividend_yield + 0.5 * volatility * volatility) * time_to_expiry_years
+    ) / variance_term
+    d2 = d1 - variance_term
+    return d1, d2
+
+
+def bs_price(
+    spot: float,
+    strike: float,
+    time_to_expiry_years: float,
+    risk_free_rate: float,
+    volatility: float,
+    dividend_yield: float,
+    right: str,
+) -> float:
+    """European option price under Black-Scholes-Merton with a continuous
+    dividend yield. Callers must ensure spot/strike/time_to_expiry_years/
+    volatility are all strictly positive - this function does not
+    neutral-default (unlike features/bond_features.py's pure functions):
+    an option price is meaningless for a degenerate input, so callers
+    (options_greeks.implied_volatility(), portfolio/options_strategy.py)
+    are responsible for filtering those cases before calling in."""
+    d1, d2 = _d1_d2(spot, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield)
+    discounted_spot = spot * math.exp(-dividend_yield * time_to_expiry_years)
+    discounted_strike = strike * math.exp(-risk_free_rate * time_to_expiry_years)
+    if right.lower() == "call":
+        return discounted_spot * _normal_cdf(d1) - discounted_strike * _normal_cdf(d2)
+    return discounted_strike * _normal_cdf(-d2) - discounted_spot * _normal_cdf(-d1)
+
+
+def delta(spot: float, strike: float, time_to_expiry_years: float, risk_free_rate: float, volatility: float, dividend_yield: float, right: str) -> float:
+    """dPrice/dSpot. Calls: [0, 1]. Puts: [-1, 0]."""
+    d1, _ = _d1_d2(spot, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield)
+    discount = math.exp(-dividend_yield * time_to_expiry_years)
+    if right.lower() == "call":
+        return discount * _normal_cdf(d1)
+    return discount * (_normal_cdf(d1) - 1.0)
+
+
+def gamma(spot: float, strike: float, time_to_expiry_years: float, risk_free_rate: float, volatility: float, dividend_yield: float) -> float:
+    """d^2Price/dSpot^2 - identical for calls and puts (no `right` param)."""
+    d1, _ = _d1_d2(spot, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield)
+    return math.exp(-dividend_yield * time_to_expiry_years) * _normal_pdf(d1) / (spot * volatility * math.sqrt(time_to_expiry_years))
+
+
+def vega(spot: float, strike: float, time_to_expiry_years: float, risk_free_rate: float, volatility: float, dividend_yield: float) -> float:
+    """dPrice/dVolatility, per 1.0 (100 percentage points) of volatility -
+    identical for calls and puts (no `right` param). Divide by 100 for the
+    conventional "per 1 vol point" quoting convention if needed."""
+    d1, _ = _d1_d2(spot, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield)
+    return spot * math.exp(-dividend_yield * time_to_expiry_years) * _normal_pdf(d1) * math.sqrt(time_to_expiry_years)
+
+
+def theta(spot: float, strike: float, time_to_expiry_years: float, risk_free_rate: float, volatility: float, dividend_yield: float, right: str) -> float:
+    """dPrice/dTime, annualized (divide by 365 for a per-calendar-day
+    figure)."""
+    d1, d2 = _d1_d2(spot, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield)
+    discounted_spot = spot * math.exp(-dividend_yield * time_to_expiry_years)
+    discounted_strike = strike * math.exp(-risk_free_rate * time_to_expiry_years)
+    decay_term = -(discounted_spot * _normal_pdf(d1) * volatility) / (2.0 * math.sqrt(time_to_expiry_years))
+    if right.lower() == "call":
+        return decay_term - risk_free_rate * discounted_strike * _normal_cdf(d2) + dividend_yield * discounted_spot * _normal_cdf(d1)
+    return decay_term + risk_free_rate * discounted_strike * _normal_cdf(-d2) - dividend_yield * discounted_spot * _normal_cdf(-d1)
+
+
+def rho(spot: float, strike: float, time_to_expiry_years: float, risk_free_rate: float, volatility: float, dividend_yield: float, right: str) -> float:
+    """dPrice/dRiskFreeRate, per 1.0 (100 percentage points) of rate."""
+    _, d2 = _d1_d2(spot, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield)
+    discounted_strike = strike * math.exp(-risk_free_rate * time_to_expiry_years)
+    if right.lower() == "call":
+        return discounted_strike * time_to_expiry_years * _normal_cdf(d2)
+    return -discounted_strike * time_to_expiry_years * _normal_cdf(-d2)
+
+
+def compute_greeks(
+    spot: float,
+    strike: float,
+    time_to_expiry_years: float,
+    risk_free_rate: float,
+    volatility: float,
+    dividend_yield: float,
+    right: str,
+) -> dict:
+    """Single call site wrapping the 5 functions above, for
+    portfolio/options_strategy.py/main.py call-site brevity."""
+    return {
+        "delta": delta(spot, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield, right),
+        "gamma": gamma(spot, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield),
+        "theta": theta(spot, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield, right),
+        "vega": vega(spot, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield),
+        "rho": rho(spot, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield, right),
+        "iv": volatility,
+    }
+
+
+def implied_volatility(
+    option_price: float,
+    spot: float,
+    strike: float,
+    time_to_expiry_years: float,
+    risk_free_rate: float,
+    dividend_yield: float,
+    right: str,
+    max_iterations: int = 100,
+    tolerance: float = 1e-6,
+) -> float | None:
+    """Safeguarded Newton-Raphson (Newton step when it stays inside the
+    current bracket, bisection step otherwise) - vega can be ~0 deep
+    ITM/OTM or near expiry, which would blow up pure Newton-Raphson.
+    bs_price() is monotonically increasing in volatility for T>0, so the
+    [low, high] bracket only ever narrows and bisection alone is already
+    guaranteed to converge; Newton just speeds that up when it's safe to
+    use.
+
+    Returns None (never raises, never NaN) when: option_price is
+    non-positive, any of spot/strike/time_to_expiry_years is non-positive,
+    option_price violates the no-arbitrage intrinsic-value bound, the
+    market price falls outside the achievable range for the search
+    bracket [1e-6, 5.0] (500% vol), or the solver fails to converge within
+    max_iterations - same "None = failed to compute, never a crash"
+    convention as features/bond_features.py::empirical_duration_beta()."""
+    if option_price is None or option_price <= 0.0 or spot <= 0.0 or strike <= 0.0 or time_to_expiry_years <= 0.0:
+        return None
+
+    right_normalized = right.lower()
+    discounted_spot = spot * math.exp(-dividend_yield * time_to_expiry_years)
+    discounted_strike = strike * math.exp(-risk_free_rate * time_to_expiry_years)
+    intrinsic = max(discounted_spot - discounted_strike, 0.0) if right_normalized == "call" else max(discounted_strike - discounted_spot, 0.0)
+    if option_price < intrinsic - tolerance:
+        return None
+
+    low, high = 1e-6, 5.0
+    price_at_low = bs_price(spot, strike, time_to_expiry_years, risk_free_rate, low, dividend_yield, right_normalized) - option_price
+    price_at_high = bs_price(spot, strike, time_to_expiry_years, risk_free_rate, high, dividend_yield, right_normalized) - option_price
+    if price_at_low > 0.0 or price_at_high < 0.0:
+        return None
+
+    sigma = 0.2
+    for _ in range(max_iterations):
+        price_diff = bs_price(spot, strike, time_to_expiry_years, risk_free_rate, sigma, dividend_yield, right_normalized) - option_price
+        if abs(price_diff) < tolerance:
+            return sigma
+
+        if price_diff > 0.0:
+            high = sigma
+        else:
+            low = sigma
+
+        option_vega = vega(spot, strike, time_to_expiry_years, risk_free_rate, sigma, dividend_yield)
+        newton_sigma = sigma - price_diff / option_vega if option_vega > 1e-10 else None
+        if newton_sigma is not None and low < newton_sigma < high:
+            sigma = newton_sigma
+        else:
+            sigma = (low + high) / 2.0
+
+    return None
+
+
+def baw_american_price(
+    spot: float,
+    strike: float,
+    time_to_expiry_years: float,
+    risk_free_rate: float,
+    dividend_yield: float,
+    volatility: float,
+    right: str,
+    max_iterations: int = 100,
+    tolerance: float = 1e-6,
+) -> float:
+    """Barone-Adesi & Whaley (1987) quadratic approximation for American
+    option prices - "Efficient Analytic Approximation of American Option
+    Values," Journal of Finance 42(2). Built entirely from this module's
+    existing bs_price()/_d1_d2()/_normal_cdf() - the European price IS the
+    approximation's own building block, not a separately-derived formula.
+    Verified numerically against a 3000-step CRR binomial tree across
+    several call/put/ITM/OTM/dividend combinations during development
+    (differences of a few cents on option prices in the $6-14 range,
+    consistent with BAW's known ~1-2% approximation error).
+
+    Never raises. Degrades to the European bs_price() value whenever: the
+    dividend yield is non-positive for a call (a call should never be
+    exercised early with zero dividend drag - the standard textbook
+    shortcut, not an approximation gap), any input is degenerate
+    (time/vol/spot/strike non-positive - returns intrinsic value in that
+    case instead), or the critical-price search fails to find a
+    bracketing sign change / doesn't converge within max_iterations. This
+    is a SAFE direction to degrade in: the American price is always >= the
+    European price, so under-pricing by falling back to the European
+    value never overstates risk in the direction that matters for a short
+    option holder (the whole reason this function exists).
+
+    Uses a safeguarded bisection search for the critical price (rather
+    than implied_volatility()'s Newton-primary approach) - the BAW
+    matching condition has no simple closed-form derivative the way vega
+    is for the IV solve, so bisection (guaranteed convergence given a
+    verified sign-changing bracket, checked explicitly before iterating)
+    is the more directly verifiable choice for a per-bar risk signal that
+    must never silently mis-converge."""
+    right_normalized = right.lower()
+    if time_to_expiry_years <= 0.0 or volatility <= 0.0 or spot <= 0.0 or strike <= 0.0:
+        return max(spot - strike, 0.0) if right_normalized == "call" else max(strike - spot, 0.0)
+
+    european_price = bs_price(spot, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield, right_normalized)
+
+    if right_normalized == "call" and dividend_yield <= 0.0:
+        return european_price
+
+    cost_of_carry = risk_free_rate - dividend_yield
+    variance = volatility * volatility
+    big_m = 2.0 * risk_free_rate / variance
+    big_n = 2.0 * cost_of_carry / variance
+    big_k = 1.0 - math.exp(-risk_free_rate * time_to_expiry_years)
+    if big_k <= 0.0:
+        return european_price
+
+    discriminant = (big_n - 1.0) ** 2 + 4.0 * big_m / big_k
+    if discriminant < 0.0:
+        return european_price
+
+    if right_normalized == "call":
+        q_root = (-(big_n - 1.0) + math.sqrt(discriminant)) / 2.0
+        if q_root <= 0.0:
+            return european_price
+
+        def matching_residual(critical_price: float) -> float:
+            d1, _ = _d1_d2(critical_price, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield)
+            euro_at_critical = bs_price(
+                critical_price, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield, "call"
+            )
+            term = (1.0 - math.exp(-dividend_yield * time_to_expiry_years) * _normal_cdf(d1)) * critical_price / q_root
+            return critical_price - strike - euro_at_critical - term
+
+        low, high = strike, max(strike, spot) * 50.0
+    else:
+        q_root = (-(big_n - 1.0) - math.sqrt(discriminant)) / 2.0
+        if q_root >= 0.0:
+            return european_price
+
+        def matching_residual(critical_price: float) -> float:
+            d1, _ = _d1_d2(critical_price, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield)
+            euro_at_critical = bs_price(
+                critical_price, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield, "put"
+            )
+            term = (1.0 - math.exp(-dividend_yield * time_to_expiry_years) * _normal_cdf(-d1)) * critical_price / q_root
+            return strike - critical_price - euro_at_critical + term
+
+        low, high = 1e-6, strike
+
+    residual_low = matching_residual(low)
+    residual_high = matching_residual(high)
+    if residual_low == 0.0:
+        critical_price = low
+    elif residual_high == 0.0:
+        critical_price = high
+    elif (residual_low > 0.0) == (residual_high > 0.0):
+        return european_price
+    else:
+        critical_price = None
+        for _ in range(max_iterations):
+            midpoint = (low + high) / 2.0
+            residual_mid = matching_residual(midpoint)
+            if abs(residual_mid) < tolerance:
+                critical_price = midpoint
+                break
+            if (residual_mid > 0.0) == (residual_low > 0.0):
+                low = midpoint
+                residual_low = residual_mid
+            else:
+                high = midpoint
+        if critical_price is None:
+            return european_price
+
+    if right_normalized == "call":
+        if spot >= critical_price:
+            return max(spot - strike, 0.0)
+        d1, _ = _d1_d2(critical_price, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield)
+        coefficient = (critical_price / q_root) * (
+            1.0 - math.exp(-dividend_yield * time_to_expiry_years) * _normal_cdf(d1)
+        )
+        return european_price + coefficient * (spot / critical_price) ** q_root
+
+    if spot <= critical_price:
+        return max(strike - spot, 0.0)
+    d1, _ = _d1_d2(critical_price, strike, time_to_expiry_years, risk_free_rate, volatility, dividend_yield)
+    coefficient = -(critical_price / q_root) * (
+        1.0 - math.exp(-dividend_yield * time_to_expiry_years) * _normal_cdf(-d1)
+    )
+    return european_price + coefficient * (spot / critical_price) ** q_root

features/sector_map.py

@@ -0,0 +1,53 @@
+"""Ticker -> sector-neutral-ranking bucket (V5.1 Phase 0, Problems.md #75).
+
+Pure, dependency-light, imported by BOTH train.py (torch-bound) and main.py
+(the Lean runtime, which cannot import train.py) - the same train/inference
+parity convention every other module in features/ follows. This module
+existed only inside train.py before V5.1; train.py::load_sector_mapping()
+is now a thin delegate to load_sector_mapping() here so both callers share
+one implementation instead of main.py duplicating the file-read/strip logic.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+UNKNOWN_SECTOR_LABEL = "Unknown"
+
+# Mirrors train.py::SECTOR_MAPPING_PATH (DATA_DIR / "reference" / "sector_mapping.json") -
+# this file lives at <repo_root>/features/sector_map.py, so .parent.parent is <repo_root>.
+DEFAULT_SECTOR_MAPPING_PATH = Path(__file__).resolve().parent.parent / "data" / "reference" / "sector_mapping.json"
+
+
+def load_sector_mapping(config: dict, *, default_path: Path = DEFAULT_SECTOR_MAPPING_PATH) -> dict[str, str]:
+    """Ticker -> sector bucket, from the checked-in data/reference/sector_mapping.json
+    (or an override path via config phase1.target.ranking.sector_neutral.mapping_path).
+
+    Same defensive posture as every other reference-file loader in this
+    codebase: returns {} (never raises) when the file is missing or
+    unparseable, so a caller degrades to every ticker resolving to
+    UNKNOWN_SECTOR_LABEL rather than crashing over a missing reference file.
+    `_`-prefixed keys are comments and are stripped.
+    """
+    mapping_path_str = (
+        config.get("phase1", {}).get("target", {}).get("ranking", {}).get("sector_neutral", {}).get("mapping_path")
+    )
+    mapping_path = Path(mapping_path_str) if mapping_path_str else default_path
+    if not mapping_path.exists():
+        return {}
+
+    try:
+        raw = json.loads(mapping_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+    return {ticker: sector for ticker, sector in raw.items() if not ticker.startswith("_")}
+
+
+def resolve_sector(ticker: str, sector_by_ticker: dict[str, str]) -> str:
+    """sector_by_ticker.get(ticker, UNKNOWN_SECTOR_LABEL) - the one-line
+    lookup every caller (book_neutrality.py, rank_book_simulator.py,
+    train.py's residual-rank sector dummies) needs, kept in one place so
+    the UNKNOWN_SECTOR_LABEL default can never drift between callers."""
+    return sector_by_ticker.get(ticker, UNKNOWN_SECTOR_LABEL)