aether-quant 0.0.1__py3-none-any.whl

features/__init__.py

@@ -0,0 +1,137 @@
+from .alt_data_features import (
+    ALT_DATA_FEATURE_NAMES,
+    FINANCIAL_CONDITIONS_CHANGE_NEUTRAL,
+    IMPLIED_VOL_TERM_STRUCTURE_NEUTRAL,
+    IMPLIED_VOLATILITY_LEVEL_NEUTRAL,
+    financial_conditions_change,
+    implied_vol_term_structure,
+    implied_volatility_level,
+)
+from .bond_features import (
+    BOND_FEATURE_NAMES,
+    CREDIT_SPREAD_LEVEL_NEUTRAL,
+    YIELD_CURVE_CURVATURE_NEUTRAL,
+    YIELD_CURVE_LEVEL_NEUTRAL,
+    analytic_convexity,
+    analytic_modified_duration,
+    bond_dv01,
+    credit_spread_level,
+    empirical_duration_beta,
+    nearest_yield_curve_point,
+    yield_curve_curvature,
+    yield_curve_level,
+    yield_curve_slope as bond_yield_curve_slope,
+)
+from .cross_asset_sensitivity import (
+    CROSS_ASSET_SENSITIVITY_FEATURE_NAMES,
+    rolling_sensitivity,
+    sensitivity_interaction,
+)
+from .derivatives_macro_features import (
+    DERIVATIVES_MACRO_FEATURE_NAMES,
+    FUTURES_MACRO_FEATURE_NAMES,
+    FUTURES_TERM_STRUCTURE_SLOPE_NEUTRAL,
+    OPTIONS_IMPLIED_VOL_SKEW_NEUTRAL,
+    OPTIONS_MACRO_FEATURE_NAMES,
+    OPTIONS_PUT_CALL_RATIO_NEUTRAL,
+    futures_term_structure_slope,
+    options_implied_vol_skew,
+    options_put_call_ratio,
+)
+from .options_greeks import (
+    baw_american_price,
+    bs_price,
+    compute_greeks,
+    delta as option_delta,
+    gamma as option_gamma,
+    implied_volatility,
+    rho as option_rho,
+    theta as option_theta,
+    vega as option_vega,
+)
+from .macro_features import (
+    CREDIT_SPREAD_NEUTRAL,
+    CRYPTO_RISK_APPETITE_NEUTRAL,
+    YIELD_CURVE_SLOPE_NEUTRAL,
+    credit_spread_proxy,
+    crypto_risk_appetite_proxy,
+    yield_curve_slope_proxy,
+)
+from .sector_map import (
+    DEFAULT_SECTOR_MAPPING_PATH,
+    UNKNOWN_SECTOR_LABEL,
+    load_sector_mapping,
+    resolve_sector,
+)
+from .technical_indicators import (
+    CROSS_SECTIONAL_MOMENTUM_RANK_NEUTRAL,
+    average_true_range_pct,
+    bollinger_pctb,
+    cross_sectional_momentum_rank,
+    distance_from_52w_high,
+    macd_histogram_normalized,
+    relative_strength_index,
+    volume_zscore,
+)
+
+__all__ = [
+    "ALT_DATA_FEATURE_NAMES",
+    "BOND_FEATURE_NAMES",
+    "CREDIT_SPREAD_LEVEL_NEUTRAL",
+    "CREDIT_SPREAD_NEUTRAL",
+    "CROSS_ASSET_SENSITIVITY_FEATURE_NAMES",
+    "CROSS_SECTIONAL_MOMENTUM_RANK_NEUTRAL",
+    "CRYPTO_RISK_APPETITE_NEUTRAL",
+    "DEFAULT_SECTOR_MAPPING_PATH",
+    "DERIVATIVES_MACRO_FEATURE_NAMES",
+    "FINANCIAL_CONDITIONS_CHANGE_NEUTRAL",
+    "FUTURES_MACRO_FEATURE_NAMES",
+    "FUTURES_TERM_STRUCTURE_SLOPE_NEUTRAL",
+    "IMPLIED_VOL_TERM_STRUCTURE_NEUTRAL",
+    "IMPLIED_VOLATILITY_LEVEL_NEUTRAL",
+    "OPTIONS_IMPLIED_VOL_SKEW_NEUTRAL",
+    "OPTIONS_MACRO_FEATURE_NAMES",
+    "OPTIONS_PUT_CALL_RATIO_NEUTRAL",
+    "UNKNOWN_SECTOR_LABEL",
+    "YIELD_CURVE_CURVATURE_NEUTRAL",
+    "YIELD_CURVE_LEVEL_NEUTRAL",
+    "YIELD_CURVE_SLOPE_NEUTRAL",
+    "analytic_convexity",
+    "analytic_modified_duration",
+    "average_true_range_pct",
+    "baw_american_price",
+    "bollinger_pctb",
+    "bond_dv01",
+    "bond_yield_curve_slope",
+    "bs_price",
+    "compute_greeks",
+    "credit_spread_level",
+    "credit_spread_proxy",
+    "cross_sectional_momentum_rank",
+    "crypto_risk_appetite_proxy",
+    "distance_from_52w_high",
+    "empirical_duration_beta",
+    "financial_conditions_change",
+    "futures_term_structure_slope",
+    "implied_vol_term_structure",
+    "implied_volatility",
+    "implied_volatility_level",
+    "load_sector_mapping",
+    "macd_histogram_normalized",
+    "nearest_yield_curve_point",
+    "option_delta",
+    "option_gamma",
+    "option_rho",
+    "option_theta",
+    "option_vega",
+    "options_implied_vol_skew",
+    "options_put_call_ratio",
+    "relative_strength_index",
+    "resolve_sector",
+    "rolling_sensitivity",
+    "sensitivity_interaction",
+    "volume_zscore",
+    "yield_curve_curvature",
+    "yield_curve_level",
+    "yield_curve_slope_proxy",
+]

features/alt_data_features.py

@@ -0,0 +1,154 @@
+"""Shared, pure alternative-data feature implementations (development/
+Problems.md #71, Phase 4.12) - additive sibling to features/bond_features.py
+and features/macro_features.py, backed by data_pipeline/fred_backfill.py's
+implied-volatility and financial-conditions series rather than price data.
+
+Broadcast identically to EVERY asset's model input (date-only, not
+asset-specific) - same "compute once per date/bar, every asset sees it"
+shape as bond_features.py/macro_features.py.
+
+Imported by BOTH train.py (offline, per-date FRED-series lookup via
+data_pipeline.fred_backfill.series_value_asof()/series_change_asof()) and
+main.py (runtime, once per bar) for parity by construction - same
+convention as features/bond_features.py.
+
+Every function neutral-defaults to 0.0 on missing input - never raises.
+The 0.0 default is chosen so it means something PLAUSIBLE, not merely
+"absent": implied_volatility_level() is a log-ratio to a reference VIX
+level (see VIX_REFERENCE_LEVEL below), so its neutral default corresponds
+to "VIX = 20," an unremarkable reading, not "VIX = 0," which cannot
+happen. This mirrors every other neutral-default in this codebase
+(bond_features.py, macro_features.py) using 0.0 to mean "no signal."
+
+These three features were chosen from a wider candidate list (VIX, VXV,
+NFCI, STLFSI4, UMCSENT, TEDRATE, SOFR, BAMLH0A0HYM2, DTWEXBGS) after
+live-verifying each one's real 2014-2021 coverage and checking pairwise
+collinearity - see data_pipeline/fred_backfill.py's
+DEFAULT_ALT_DATA_REFERENCE_SERIES docstring for the rejected candidates
+and why. The surviving three are deliberately NOT redundant with each
+other or with the existing 8 bond_* features: implied_volatility_level
+alone cannot distinguish the 2019-12-27..2020-03-25 COVID-crash era (mean
+VIX 28.54) from the immediately-following recovery era (mean VIX 29.24) -
+term structure and financial-conditions CHANGE can (measured: term
+structure mean +0.013 during the crash vs +0.105 after; NFCI 4-week
+change mean +0.154/max +0.608 during the crash vs a total 2014-2019 range
+of [-0.091, +0.091]).
+"""
+
+from __future__ import annotations
+
+import math
+
+IMPLIED_VOLATILITY_LEVEL_NEUTRAL = 0.0
+IMPLIED_VOL_TERM_STRUCTURE_NEUTRAL = 0.0
+FINANCIAL_CONDITIONS_CHANGE_NEUTRAL = 0.0
+REAL_RATE_CHANGE_NEUTRAL = 0.0
+BREAKEVEN_INFLATION_CHANGE_NEUTRAL = 0.0
+DOLLAR_INDEX_CHANGE_NEUTRAL = 0.0
+
+# Divisor for implied_volatility_level()'s log-ratio - an unremarkable,
+# roughly-median VIX reading (measured p50 15.1 over the 2014-12..2021-03
+# common_window), chosen so the neutral default (log(1.0) = 0.0) maps back
+# to a plausible market state rather than an impossible one (a raw VIX
+# feature's 0.0 default would mean "VIX = 0", which never happens).
+VIX_REFERENCE_LEVEL = 20.0
+
+ALT_DATA_FEATURE_NAMES = [
+    "alt_implied_volatility_level",
+    "alt_implied_vol_term_structure",
+    "alt_financial_conditions_change",
+]
+
+
+def implied_volatility_level(vix_close: float | None) -> float:
+    """log(VIX / VIX_REFERENCE_LEVEL). VIX is right-skewed (measured p50
+    15.1 / p90 26.7 / p99 53.9 over the common_window) - a raw level would
+    let extreme prints (82.69 in March 2020) dominate the feature scaler's
+    clip/winsorize range; the log compresses that skew the same way
+    close_to_close_return features already use log-scale-friendly
+    transforms elsewhere in this codebase. Returns
+    IMPLIED_VOLATILITY_LEVEL_NEUTRAL (0.0) when vix_close is missing or
+    non-positive (a non-positive VIX reading is not physically meaningful
+    - never log() a non-positive number)."""
+    if vix_close is None or vix_close <= 0.0:
+        return IMPLIED_VOLATILITY_LEVEL_NEUTRAL
+    return math.log(float(vix_close) / VIX_REFERENCE_LEVEL)
+
+
+def implied_vol_term_structure(vix_close: float | None, vix_3m_close: float | None) -> float:
+    """(VIX 3-month - VIX) / VIX - positive means contango (the market is
+    calm: longer-dated implied vol priced higher than spot), negative
+    means backwardation (stress RIGHT NOW: spot implied vol priced above
+    the 3-month tenor, since a acute near-term shock is expected to fade).
+    Normalized by the spot VIX level so the ratio is comparable across
+    vol regimes - the whole reason this feature exists alongside
+    implied_volatility_level() rather than instead of it: VIX level alone
+    cannot separate the COVID-crash era from the immediately-following
+    recovery era (both ~28-29 mean VIX), while term structure can (+0.013
+    during the crash vs +0.105 after, with a -0.256 backwardation minimum
+    during the crash). Returns IMPLIED_VOL_TERM_STRUCTURE_NEUTRAL (0.0)
+    when either leg is missing or vix_close is non-positive."""
+    if vix_close is None or vix_3m_close is None or vix_close <= 0.0:
+        return IMPLIED_VOL_TERM_STRUCTURE_NEUTRAL
+    return (float(vix_3m_close) - float(vix_close)) / float(vix_close)
+
+
+def financial_conditions_change(nfci_now: float | None, nfci_prior: float | None) -> float:
+    """NFCI(t) - NFCI(t - 4 weeks) - the Chicago Fed National Financial
+    Conditions Index's own 4-week CHANGE, not its level. The level is
+    deliberately not a feature here: measured correlation of rho=0.73
+    against the existing bond_credit_spread_level feature (BAA10Y), i.e.
+    the model already has substantially the same information via that
+    channel. The 4-week CHANGE is a genuinely different signal (rho=0.23
+    against bond_credit_spread_level) - a near-binary "conditions are
+    tightening violently right now" indicator: measured mean +0.154 (max
+    +0.608) during the 2019-12-27..2020-03-25 COVID-crash era, versus a
+    total 2014-12..2019-12 pre-COVID range of only [-0.091, +0.091] - the
+    crash reading sits roughly 6.7x outside five years of prior variation.
+    Returns FINANCIAL_CONDITIONS_CHANGE_NEUTRAL (0.0) when either endpoint
+    is missing (e.g. fewer than 4 weeks of history available yet, or the
+    series cache is absent)."""
+    if nfci_now is None or nfci_prior is None:
+        return FINANCIAL_CONDITIONS_CHANGE_NEUTRAL
+    return float(nfci_now) - float(nfci_prior)
+
+
+def real_rate_change(real_rate_now: float | None, real_rate_prior: float | None) -> float:
+    """DFII10(t) - DFII10(t - N) - the 10-year TIPS (real) yield's own
+    CHANGE, not its level. V5.1 Phase 2 (item 8 / F2, development/
+    Problems.md): a stationary driver for
+    features/cross_asset_sensitivity.py's per-asset real-rate sensitivity
+    beta - a level would be non-stationary and comparing betas fit against
+    a trending regressor across different market eras is not meaningful,
+    the same reasoning financial_conditions_change() above already
+    documents for NFCI. Returns REAL_RATE_CHANGE_NEUTRAL (0.0) when either
+    endpoint is missing."""
+    if real_rate_now is None or real_rate_prior is None:
+        return REAL_RATE_CHANGE_NEUTRAL
+    return float(real_rate_now) - float(real_rate_prior)
+
+
+def breakeven_inflation_change(breakeven_now: float | None, breakeven_prior: float | None) -> float:
+    """T10YIE(t) - T10YIE(t - N) - the 10-year breakeven inflation rate's
+    own CHANGE. Same stationarity reasoning as real_rate_change() above -
+    a driver for features/cross_asset_sensitivity.py, not a broadcast
+    level feature. Returns BREAKEVEN_INFLATION_CHANGE_NEUTRAL (0.0) when
+    either endpoint is missing."""
+    if breakeven_now is None or breakeven_prior is None:
+        return BREAKEVEN_INFLATION_CHANGE_NEUTRAL
+    return float(breakeven_now) - float(breakeven_prior)
+
+
+def dollar_index_change(dollar_index_now: float | None, dollar_index_prior: float | None) -> float:
+    """DTWEXBGS(t) - DTWEXBGS(t - N) - the trade-weighted dollar index's
+    own CHANGE. Same stationarity reasoning as real_rate_change() above -
+    a driver for features/cross_asset_sensitivity.py, not a broadcast
+    level feature (see data_pipeline/fred_backfill.py's
+    DEFAULT_ALT_DATA_REFERENCE_SERIES docstring for why DTWEXBGS is being
+    re-added as a sensitivity driver rather than a level, having
+    previously been evaluated and left out of the original alt-data
+    trio). Returns DOLLAR_INDEX_CHANGE_NEUTRAL (0.0) when either endpoint
+    is missing."""
+    if dollar_index_now is None or dollar_index_prior is None:
+        return DOLLAR_INDEX_CHANGE_NEUTRAL
+    return float(dollar_index_now) - float(dollar_index_prior)

features/bond_features.py

@@ -0,0 +1,275 @@
+"""Shared, pure real-yield-curve/credit-spread/duration feature
+implementations - additive sibling to features/macro_features.py, using
+data_pipeline/fred_backfill.py's actual FRED Treasury-yield/credit-spread
+series rather than macro_features.py's bond-ETF-price-momentum proxies.
+
+Broadcast identically to EVERY asset's model input (not just bond-tagged
+assets) - same "compute once per date/bar, every asset sees it" shape as
+macro_features.py, and the concrete mechanism by which bond/yield-curve
+signal becomes usable for equity/crypto/future/option predictions too, not
+just bonds themselves.
+
+Imported by BOTH train.py (offline, per-date FRED-series lookup) and
+main.py (runtime, once per bar) for parity by construction - same
+convention as features/technical_indicators.py and features/macro_features.py.
+
+Every function neutral-defaults to 0.0 on missing input - never raises -
+except empirical_duration_beta(), which returns None (not 0.0) below its
+minimum-observation floor: an unknown duration sensitivity must never be
+indistinguishable from a genuinely-zero one, the same "None = absent, 0.0 =
+neutral" distinction risk/position_sizing.py::rank_sizing_multiplier()
+already draws for missing rank predictions.
+
+V4.6 (development/Problems.md, Roadmap "Assets" - "single-bond trading")
+added analytic_modified_duration()/analytic_convexity()/bond_dv01(), a
+real closed-form bond-math sibling to empirical_duration_beta() above -
+NOT a replacement for it. Individual-bond trading was confirmed
+INFEASIBLE under this Lean version's security model (no SecurityType.Bond,
+no AddBond, no Common/Securities/Bond/ implementation anywhere in the real
+Lean source tree - every "bond" Lean supports is an equity-typed ETF
+wrapper, exactly what this codebase already does) - these 3 functions
+instead deepen the EXISTING bond-ETF sleeve's analytics, using
+bond_metadata.duration_proxy_years (already configured per-ETF in
+config.json) as an assumed maturity and bond_metadata.assumed_coupon_rate
+(or, when absent, the treasury yield-curve point nearest that maturity, as
+an at-par-pricing proxy coupon) as an assumed coupon - explicitly an
+ETF-level APPROXIMATION, not real per-bond cash-flow data.
+
+V4.7 merged these 3 functions' output into base_features/BOND_FEATURE_NAMES
+as real model inputs (main.py::_build_model_input_impl(),
+train.py::build_bond_features_by_date()) - code-complete, but deploying it
+live requires running a retrain first: config.json's
+phase1.features.input_set now lists the 3 new names, and main.py's
+scaling loop indexes base_features[name] with no default, so an
+un-retrained ml/feature_schema.json (still listing only the original 34
+names) would KeyError on the very next bar. Until that retrain runs,
+main.py's own latest_bond_analytics_by_symbol side-table remains the only
+place these values are actually visible (dashboard/state), same as before.
+"""
+
+from __future__ import annotations
+
+YIELD_CURVE_LEVEL_NEUTRAL = 0.0
+YIELD_CURVE_SLOPE_NEUTRAL = 0.0
+YIELD_CURVE_CURVATURE_NEUTRAL = 0.0
+CREDIT_SPREAD_LEVEL_NEUTRAL = 0.0
+
+BOND_FEATURE_NAMES = [
+    "bond_yield_curve_level",
+    "bond_yield_curve_slope",
+    "bond_yield_curve_curvature",
+    "bond_credit_spread_level",
+    "bond_empirical_duration_beta",
+    "bond_analytic_modified_duration",
+    "bond_analytic_convexity",
+    "bond_dv01",
+]
+
+
+def yield_curve_level(treasury_10yr_yield: float | None) -> float:
+    """Raw level of the 10yr Treasury yield (e.g. 0.045 for 4.5%). Returns
+    YIELD_CURVE_LEVEL_NEUTRAL (0.0) when unavailable."""
+    if treasury_10yr_yield is None:
+        return YIELD_CURVE_LEVEL_NEUTRAL
+    return float(treasury_10yr_yield)
+
+
+def yield_curve_slope(treasury_10yr_yield: float | None, treasury_3mo_yield: float | None) -> float:
+    """10yr - 3mo - the standard recession-signal curve slope (negative =
+    inverted curve). Real-data replacement for
+    macro_features.yield_curve_slope_proxy()'s price-momentum proxy.
+    Returns YIELD_CURVE_SLOPE_NEUTRAL (0.0) when either input is missing."""
+    if treasury_10yr_yield is None or treasury_3mo_yield is None:
+        return YIELD_CURVE_SLOPE_NEUTRAL
+    return float(treasury_10yr_yield) - float(treasury_3mo_yield)
+
+
+def yield_curve_curvature(
+    treasury_2yr_yield: float | None,
+    treasury_5yr_yield: float | None,
+    treasury_10yr_yield: float | None,
+) -> float:
+    """2*5yr - 2yr - 10yr - the standard butterfly/curvature measure of
+    curve shape independent of its overall level or slope. Returns
+    YIELD_CURVE_CURVATURE_NEUTRAL (0.0) when any input is missing."""
+    if treasury_2yr_yield is None or treasury_5yr_yield is None or treasury_10yr_yield is None:
+        return YIELD_CURVE_CURVATURE_NEUTRAL
+    return 2.0 * float(treasury_5yr_yield) - float(treasury_2yr_yield) - float(treasury_10yr_yield)
+
+
+def credit_spread_level(baa10y_spread: float | None) -> float:
+    """Raw BAA10Y (Moody's Baa corporate bond yield relative to the 10yr
+    Treasury) level - widens when credit risk appetite deteriorates.
+    Real-data replacement for macro_features.credit_spread_proxy()'s
+    momentum-based proxy. Returns CREDIT_SPREAD_LEVEL_NEUTRAL (0.0) when
+    unavailable."""
+    if baa10y_spread is None:
+        return CREDIT_SPREAD_LEVEL_NEUTRAL
+    return float(baa10y_spread)
+
+
+def empirical_duration_beta(
+    etf_daily_returns: list[float | None],
+    delta_10yr_yield_daily: list[float | None],
+    min_observations: int = 60,
+) -> float | None:
+    """Rolling OLS slope of ETF daily returns regressed on same-day
+    Delta-10yr-yield: an empirical "how much does this ETF move per unit of
+    yield change" duration proxy, since these are ETFs with no single
+    stated maturity, not individual bonds with a textbook duration figure.
+
+    Pairs the two series positionally (index i of each list must already
+    correspond to the same trading date - callers are responsible for
+    alignment), drops any pair where either side is None, and requires at
+    least min_observations valid pairs. Returns None (not 0.0) below that
+    floor - a missing/insufficient-history duration estimate must be
+    distinguishable from "genuinely zero duration sensitivity"."""
+    paired = [
+        (x, y)
+        for x, y in zip(etf_daily_returns, delta_10yr_yield_daily)
+        if x is not None and y is not None
+    ]
+    if len(paired) < min_observations:
+        return None
+
+    xs = [float(pair[1]) for pair in paired]
+    ys = [float(pair[0]) for pair in paired]
+    mean_x = sum(xs) / len(xs)
+    mean_y = sum(ys) / len(ys)
+    covariance = sum((x - mean_x) * (y - mean_y) for x, y in zip(xs, ys))
+    variance_x = sum((x - mean_x) ** 2 for x in xs)
+    # An exact `== 0.0` check is not robust here: for a mathematically
+    # constant xs, whether mean_x/variance_x round to exactly 0.0 depends on
+    # sum()'s internal summation algorithm, which CPython changed (naive
+    # left-to-right -> compensated) between 3.11 and 3.12 - the same input
+    # can produce a true 0.0 on one Python version and a tiny rounding-noise
+    # variance (~1e-20 scale, versus real delta-yield variance on the order
+    # of 1e-4 to 1e-8) on another, silently producing a wild
+    # covariance/near-zero-noise ratio instead of the intended None. See
+    # development/Problems.md#10.
+    if variance_x < 1e-12:
+        return None
+    return covariance / variance_x
+
+
+def _bond_cash_flows(coupon_rate: float, years_to_maturity: float, payments_per_year: int, face_value: float = 100.0) -> list[float]:
+    """Coupon + principal cash-flow schedule for a plain-vanilla,
+    fixed-coupon bond priced at face_value=100 (a standard convention -
+    duration/convexity are scale-invariant per-unit-price ratios, so the
+    actual face value used doesn't affect the resulting figures). One
+    entry per period; the LAST entry additionally includes the face_value
+    repayment. Returns [] for a non-positive period count."""
+    num_periods = max(int(round(years_to_maturity * payments_per_year)), 0)
+    if num_periods == 0:
+        return []
+    coupon_per_period = coupon_rate / payments_per_year * face_value
+    cash_flows = [coupon_per_period] * num_periods
+    cash_flows[-1] += face_value
+    return cash_flows
+
+
+def analytic_modified_duration(
+    yield_to_maturity: float | None,
+    coupon_rate: float | None,
+    years_to_maturity: float | None,
+    payments_per_year: int = 2,
+) -> float | None:
+    """Standard closed-form modified duration from a plain-vanilla,
+    fixed-coupon cash-flow schedule: Macaulay duration (the price-weighted
+    average time to each cash flow, in years) divided by
+    (1 + yield_to_maturity/payments_per_year).
+
+    A genuinely DIFFERENT estimate from empirical_duration_beta() above,
+    not a replacement for it: empirical_duration_beta() measures how much
+    an ETF's OWN observed price actually moved per unit of yield change (a
+    market-realized sensitivity); this function computes what a
+    HYPOTHETICAL plain-vanilla bond with the given yield/coupon/maturity
+    would theoretically be sensitive to, from cash-flow math alone - see
+    this module's own docstring for the ETF-level-approximation caveat on
+    what yield_to_maturity/coupon_rate/years_to_maturity should be sourced
+    from in practice.
+
+    Returns None (never raises) when any input is missing, years_to_maturity
+    is non-positive, or the computed price is non-positive (a degenerate/
+    extreme-negative-yield edge case) - an unknown/undefined duration must
+    never be indistinguishable from a genuinely-zero one, the same
+    convention empirical_duration_beta() already established."""
+    if yield_to_maturity is None or coupon_rate is None or years_to_maturity is None or years_to_maturity <= 0:
+        return None
+    period_yield = float(yield_to_maturity) / payments_per_year
+    if period_yield <= -1.0:
+        return None
+    cash_flows = _bond_cash_flows(float(coupon_rate), float(years_to_maturity), payments_per_year)
+    if not cash_flows:
+        return None
+
+    discounted = [cf / (1.0 + period_yield) ** (t + 1) for t, cf in enumerate(cash_flows)]
+    price = sum(discounted)
+    if price <= 0.0:
+        return None
+    weighted_time = sum(((t + 1) / payments_per_year) * pv for t, pv in enumerate(discounted))
+    macaulay_duration = weighted_time / price
+    return macaulay_duration / (1.0 + period_yield)
+
+
+def analytic_convexity(
+    yield_to_maturity: float | None,
+    coupon_rate: float | None,
+    years_to_maturity: float | None,
+    payments_per_year: int = 2,
+) -> float | None:
+    """Standard closed-form convexity (the second derivative of bond price
+    with respect to yield, annualized) from the same plain-vanilla
+    cash-flow schedule analytic_modified_duration() uses - same
+    ETF-level-approximation caveat and degrade-to-None convention."""
+    if yield_to_maturity is None or coupon_rate is None or years_to_maturity is None or years_to_maturity <= 0:
+        return None
+    period_yield = float(yield_to_maturity) / payments_per_year
+    if period_yield <= -1.0:
+        return None
+    cash_flows = _bond_cash_flows(float(coupon_rate), float(years_to_maturity), payments_per_year)
+    if not cash_flows:
+        return None
+
+    discounted = [cf / (1.0 + period_yield) ** (t + 1) for t, cf in enumerate(cash_flows)]
+    price = sum(discounted)
+    if price <= 0.0:
+        return None
+    convexity_sum = sum(
+        (t + 1) * (t + 2) * pv / (1.0 + period_yield) ** 2 for t, pv in enumerate(discounted)
+    )
+    return convexity_sum / (price * payments_per_year ** 2)
+
+
+def bond_dv01(price: float | None, modified_duration: float | None, notional: float = 1.0) -> float | None:
+    """Dollar duration per 1bp yield move (DV01):
+    price * modified_duration * 0.0001 * notional - a directly useful
+    risk-sizing number (expected dollar P&L for a 1 basis point yield
+    change). Returns None (never raises) when price/modified_duration is
+    missing, or price/notional is non-positive."""
+    if price is None or modified_duration is None or price <= 0.0 or notional <= 0.0:
+        return None
+    return float(price) * float(modified_duration) * 0.0001 * float(notional)
+
+
+def nearest_yield_curve_point(years_to_maturity: float | None, curve_points: dict) -> float | None:
+    """Picks the yield-curve observation whose maturity (in years, the
+    dict's keys) is CLOSEST to years_to_maturity - the at-par-pricing
+    proxy coupon/yield fallback analytic_modified_duration()/
+    analytic_convexity() need when bond_metadata.assumed_coupon_rate isn't
+    explicitly configured for an ETF. A coarse approximation by
+    construction (this codebase's own Treasury curve only has 4 points -
+    3mo/2yr/5yr/10yr - so a long-duration ETF's true maturity is
+    necessarily approximated by the longest available point); callers
+    already document that limitation, this function just picks the
+    nearest one rather than guessing further. Skips any None-valued point
+    (a FRED series with no observation as-of the current date) - returns
+    None (never raises) when no curve point has a value at all, or
+    years_to_maturity is None."""
+    if years_to_maturity is None:
+        return None
+    usable_points = {maturity: yield_value for maturity, yield_value in curve_points.items() if yield_value is not None}
+    if not usable_points:
+        return None
+    nearest_maturity = min(usable_points, key=lambda maturity: abs(maturity - years_to_maturity))
+    return usable_points[nearest_maturity]

features/cross_asset_sensitivity.py

@@ -0,0 +1,79 @@
+"""Per-asset macro sensitivities (V5.1 Phase 2, item 8 / F2 of the plan) -
+additive sibling to features/bond_features.py, features/macro_features.py,
+features/alt_data_features.py.
+
+F2's finding: every existing macro_*/bond_*/alt_* feature (except
+bond_empirical_duration_beta) is written IDENTICALLY to every asset's row
+on a date - a per-date constant that shifts every asset's score equally,
+which a cross-sectional ranker is by construction invariant to (Spearman/
+ListNet ignore any transform that preserves relative order within a date).
+"Add more macro features," taken literally, is near-worthless for a rank
+model. The version that works is a per-asset SENSITIVITY: how much does
+THIS asset's return move per unit of macro change - a quantity that varies
+across the cross-section, plus the interaction term (sensitivity x today's
+macro move), which is the closest thing to a forward-looking macro-driven
+return prediction that stays scale-consistent asset to asset.
+
+Imported by BOTH train.py (offline, per-date/per-asset rolling regression
+over the full history) and main.py (runtime, once per symbol per bar using
+the same rolling-deque pattern main.py's
+_bond_empirical_duration_beta_for_symbol() already established) for
+train/inference parity by construction - same convention as every other
+features/ module. main.py cannot import train.py (torch), which is the
+whole reason this module lives here rather than in train.py alongside
+build_cross_asset_sensitivity_features().
+"""
+
+from __future__ import annotations
+
+from features.bond_features import empirical_duration_beta
+
+CROSS_ASSET_SENSITIVITY_FEATURE_NAMES = [
+    "sens_vix_beta",
+    "sens_vix_interaction",
+    "sens_real_rate_beta",
+    "sens_real_rate_interaction",
+    "sens_credit_beta",
+    "sens_credit_interaction",
+    "sens_dollar_beta",
+    "sens_dollar_interaction",
+]
+
+
+def rolling_sensitivity(
+    asset_returns: list[float | None],
+    macro_changes: list[float | None],
+    *,
+    lookback: int,
+    min_observations: int,
+) -> float | None:
+    """Trailing-window OLS slope of asset_returns on macro_changes,
+    restricted to the last `lookback` positions of each series (positionally
+    paired - callers are responsible for date alignment, the same contract
+    empirical_duration_beta() itself already documents). A thin wrapper -
+    REUSES empirical_duration_beta() rather than reimplementing OLS, exactly
+    as bond_empirical_duration_beta already does for a whole-history
+    (non-rolling) beta.
+
+    lookback <= 0 disables windowing (uses the full series - a whole-history
+    beta, matching bond_empirical_duration_beta's convention). Returns None
+    (not 0.0) when fewer than min_observations valid pairs exist in the
+    window - a missing/insufficient-history sensitivity must stay
+    distinguishable from a genuinely-zero one, same as
+    empirical_duration_beta()'s own return contract."""
+    if lookback > 0:
+        asset_returns = asset_returns[-lookback:]
+        macro_changes = macro_changes[-lookback:]
+    return empirical_duration_beta(asset_returns, macro_changes, min_observations=min_observations)
+
+
+def sensitivity_interaction(sensitivity: float | None, macro_change: float | None) -> float:
+    """beta_i * delta_macro_t - the interaction term that turns a per-date
+    constant macro move into a per-asset-varying signal a cross-sectional
+    ranker can actually use. Neutral 0.0 on any missing input, the same
+    "None input -> 0.0 neutral output" convention every features/*.py
+    interaction/composite function already follows (e.g.
+    features/alt_data_features.py's own neutral defaults)."""
+    if sensitivity is None or macro_change is None:
+        return 0.0
+    return float(sensitivity) * float(macro_change)