aether-quant 0.0.1__py3-none-any.whl

portfolio/rank_signal.py

@@ -0,0 +1,219 @@
+"""Rank signal resolution and cross-sectional normalization (V5.1 Phase 1,
+development/Problems.md #73 - the sigmoid-at-inference/raw-at-training
+mismatch). Two responsibilities, both pure:
+
+1. WHICH head(s) drive live trading - previously hardcoded in main.py
+   (always prefer the sequence model's rank_20d, fall back to multitask's),
+   now a config-driven, promotion-gate-aware blend resolved once per run.
+2. HOW that raw score becomes a [0,1] rank - previously a raw model output
+   passed straight through (which, combined with a since-fixed sigmoid/raw
+   training mismatch, meant live values compressed into roughly
+   [0.5, 0.7] instead of spanning [0,1] - IC is invariant to any monotone
+   transform, which is exactly why no rank-IC-based gate ever caught it).
+   Cross-sectional percentile normalization, computed fresh each bar over
+   whichever symbols have a raw score, is the fix that survives regardless
+   of what scale the underlying model head happens to output at - the
+   same reasoning train.py::_rank_ic_from_arrays() already documents for
+   why it ranks predictions before comparing them.
+"""
+
+from __future__ import annotations
+
+
+def resolve_rank_signal_policy(training_metrics_by_model: dict[str, dict | None], config: dict) -> dict:
+    """Resolved ONCE in main.py::Initialize() (never per-bar - the
+    promotion-gate verdicts this reads only change when a new model is
+    installed). Reads phase_v2.rank_signal:
+
+      heads: {"rank_20d": 1.0, "rank_5d": 0.0} - the blend weights.
+      model_priority: ["sequence", "multitask"] - which model's value for
+        a given head wins when both are available.
+      demote_not_promotable_heads: when true, a head whose backtest
+        promotion-gate verdict (backtest.{head}_ranking_quality.quality_status,
+        checked against the FIRST model in model_priority that has a
+        verdict for it - the same precedence select_raw_rank_score() uses
+        at runtime) is not in min_promotion_status has its weight zeroed
+        and redistributed proportionally across the surviving heads.
+        A head configured at weight 0.0 is still checked and can still
+        become a survivor - "listed with zero weight" means "tracked,
+        currently inactive," not "not configured" (development/Problems.md);
+        it only actually receives weight if every positively-weighted head
+        gets demoted, in which case survivors split the freed weight
+        equally rather than dividing by the now-zero surviving total.
+
+    Returns {"heads": {...}, "model_priority": [...], "normalization": ...,
+    "demoted": [...], "reason": "..."}.
+
+    FAIL-OPEN, always: never raises. Missing/unreadable metrics for a head
+    leave that head's configured weight untouched (a promotion verdict
+    that cannot be checked is not evidence of a problem). If demotion
+    would zero out EVERY head's weight, the entire operation is skipped
+    and the originally configured policy is returned unchanged, with
+    reason recording why - demoting every head would silently stop the
+    book from ever engaging, a far bigger behavior change than "prefer a
+    different head" implies.
+    """
+    rank_signal_config = config.get("phase_v2", {}).get("rank_signal", {})
+    heads = dict(rank_signal_config.get("heads", {"rank_20d": 1.0}))
+    model_priority = list(rank_signal_config.get("model_priority", ["sequence", "multitask"]))
+    normalization = str(rank_signal_config.get("normalization", "cross_sectional"))
+    demote_enabled = bool(rank_signal_config.get("demote_not_promotable_heads", True))
+    min_promotion_status = set(rank_signal_config.get("min_promotion_status", ["promotable", "watchlist"]))
+
+    if not demote_enabled or not heads:
+        return {
+            "heads": heads, "model_priority": model_priority, "normalization": normalization,
+            "demoted": [], "reason": "demotion_disabled_or_no_heads_configured",
+        }
+
+    demoted: list[str] = []
+    surviving_heads: dict[str, float] = {}
+    for head_name, weight in heads.items():
+        status = _resolve_head_quality_status(head_name, model_priority, training_metrics_by_model)
+        if status is None or status in min_promotion_status:
+            surviving_heads[head_name] = weight
+        elif weight > 0.0:
+            # A head already at 0.0 weight can't be meaningfully "demoted"
+            # (there's nothing to redistribute away from it) - only a
+            # positively-weighted head's demotion is worth recording.
+            demoted.append(head_name)
+
+    if not surviving_heads:
+        # Demoting every head would silently stop the book from ever
+        # engaging - a far bigger behavior change than "prefer a
+        # different head" implies. Leave the configured policy untouched.
+        return {
+            "heads": heads, "model_priority": model_priority, "normalization": normalization,
+            "demoted": [], "reason": "all_heads_would_be_demoted_policy_unchanged",
+        }
+
+    total_weight = sum(surviving_heads.values())
+    if total_weight > 0.0:
+        redistributed = {name: weight / total_weight for name, weight in surviving_heads.items()}
+    else:
+        # Every positively-weighted head got demoted, leaving only
+        # zero-weight survivors (heads tracked but not currently primary) -
+        # split the freed weight equally among them rather than dividing
+        # by a zero total.
+        redistributed = {name: 1.0 / len(surviving_heads) for name in surviving_heads}
+    # Zero-weighted entries for demoted heads are kept (not dropped) so
+    # select_raw_rank_score()'s blend loop can still see - and skip - them
+    # without a KeyError, and so state.json's rank_head_weights stays a
+    # complete, auditable record of every configured head.
+    for head_name in heads:
+        redistributed.setdefault(head_name, 0.0)
+
+    reason = "no_demotion_needed" if not demoted else f"demoted:{','.join(demoted)}"
+    return {
+        "heads": redistributed, "model_priority": model_priority, "normalization": normalization,
+        "demoted": demoted, "reason": reason,
+    }
+
+
+def _resolve_head_quality_status(
+    head_name: str, model_priority: list[str], training_metrics_by_model: dict[str, dict | None]
+) -> str | None:
+    """First model in model_priority that has a backtest ranking_quality
+    verdict for `head_name` wins - the same precedence
+    select_raw_rank_score() uses to pick which model's VALUE feeds the
+    blend, so the demotion decision and the runtime value come from the
+    same model whenever possible. Returns None (never raises) when no
+    configured model has a verdict for this head - e.g. an older metrics
+    file predating this head, or the metrics file missing entirely."""
+    for model_name in model_priority:
+        metrics = training_metrics_by_model.get(model_name)
+        if not metrics:
+            continue
+        quality = (metrics.get("backtest", {}) or {}).get(f"{head_name}_ranking_quality")
+        if quality:
+            return quality.get("quality_status")
+    return None
+
+
+def select_raw_rank_score(
+    sequence_prediction: dict | None, multitask_payload: dict | None, policy: dict
+) -> tuple[float | None, str]:
+    """Replaces main.py's previous hardcode (always prefer the sequence
+    model's rank_20d, fall back to multitask's). Now a weighted blend
+    across policy["heads"], each head's own value resolved via
+    policy["model_priority"] (sequence before multitask, by default).
+
+    Returns (score, source) where source records exactly which heads/
+    models contributed, e.g. "sequence:0.6*rank_5d+0.4*rank_20d" or
+    "sequence:1.0*rank_20d,multitask:1.0*rank_5d" when different heads
+    come from different models. Returns (None, "no_rank_available") when
+    no configured head has a value from any model this bar (e.g. every
+    model still warming up)."""
+    payload_by_model = {"sequence": sequence_prediction, "multitask": multitask_payload}
+    model_priority = policy.get("model_priority", ["sequence", "multitask"])
+    heads = policy.get("heads", {})
+
+    weighted_sum = 0.0
+    total_weight_used = 0.0
+    contributions: list[str] = []
+
+    for head_name, weight in heads.items():
+        if weight <= 0.0:
+            continue
+        value, model_used = _resolve_head_value(head_name, model_priority, payload_by_model)
+        if value is None:
+            continue
+        weighted_sum += weight * float(value)
+        total_weight_used += weight
+        contributions.append(f"{model_used}:{weight:g}*{head_name}")
+
+    if total_weight_used <= 0.0:
+        return None, "no_rank_available"
+
+    score = weighted_sum / total_weight_used
+    source = ",".join(contributions)
+    return score, source
+
+
+def _resolve_head_value(
+    head_name: str, model_priority: list[str], payload_by_model: dict[str, dict | None]
+) -> tuple[float | None, str | None]:
+    for model_name in model_priority:
+        payload = payload_by_model.get(model_name)
+        if payload and payload.get(head_name) is not None:
+            return float(payload[head_name]), model_name
+    return None, None
+
+
+def cross_sectional_rank_scores(scores_by_symbol: dict[str, float]) -> dict[str, float]:
+    """Per-bar percentile rank across whatever symbols have a raw score
+    this bar, ties averaged (matching pandas' `.rank(pct=True)` semantics -
+    the same transform train.py::_rank_ic_from_arrays() applies to
+    predictions before computing rank-IC, so a raw score's absolute scale
+    can never matter, only its ordering within this bar's cross-section).
+    Pure Python - no pandas import on the runtime hot path.
+
+    <=1 eligible symbol returns {} (no meaningful cross-section to rank
+    within, so the book has no view this bar) - NEVER a spurious 0.5 for
+    a lone symbol, which would silently look like "predicted median"
+    rather than "no ranking possible."."""
+    if len(scores_by_symbol) <= 1:
+        return {}
+
+    ordered = sorted(scores_by_symbol.items(), key=lambda item: item[1])
+    n = len(ordered)
+
+    # Average-rank tie handling: every symbol sharing a raw score value
+    # gets the mean of the positions that tied group would have spanned.
+    ranks: dict[str, float] = {}
+    index = 0
+    while index < n:
+        group_end = index
+        while group_end + 1 < n and ordered[group_end + 1][1] == ordered[index][1]:
+            group_end += 1
+        # Positions are 1-indexed for the standard rank formula; percentile
+        # rank then divides by n so ties land on the correct SHARED
+        # percentile rather than each tied member getting a distinct one.
+        average_position = (index + 1 + group_end + 1) / 2.0
+        percentile = average_position / n
+        for tied_index in range(index, group_end + 1):
+            symbol = ordered[tied_index][0]
+            ranks[symbol] = percentile
+        index = group_end + 1
+
+    return ranks

portfolio/rolling_ic_gate.py

@@ -0,0 +1,183 @@
+"""V5.3.5 (development/Problems.md #102): a rolling TRAILING realized-IC
+gate for book engagement - the direct sibling of
+portfolio/book_construction.py::compute_confidence_spread()'s consumer in
+_select_book_group(), added because dispersion and skill turned out to be
+different things a real backtest could tell apart even when the existing
+min_rank_confidence_spread gate couldn't.
+
+Background: #102 found that lowering min_rank_confidence_spread (which
+only measures whether the model's raw scores are DISPERSED today) let the
+live book trade through real, historically bad stretches where the
+model's own per-era IC diagnostic (#71) is near-zero or negative - a
+day's scores can look perfectly "spread out" while carrying zero genuine
+predictive validity. This module adds an independent, second veto based
+on TRAILING REALIZED IC (was the model actually right, recently) rather
+than same-day dispersion.
+
+Deliberately its own module, not folded into book_construction.py or
+risk/kill_switch.py:
+  - book_construction.py is same-bar cross-sectional selection math with
+    no temporal/resolution state today (compute_confidence_spread() reads
+    only this bar's own scores). This gate needs a multi-bar buffer and a
+    "wait for the future, then resolve" shape - closer in spirit to
+    evaluation/kill_switch_replay.py's day-by-day state-carry pattern -
+    and deserves its own independently-testable home, the same
+    relationship portfolio/book_neutrality.py already has to
+    book_construction.py (a sibling module, imported by main.py's call
+    site, not inlined).
+  - risk/kill_switch.py already has a dormant `min_live_rank_ic`
+    condition, but it reads `live_rank_ic` from a locally-cached file
+    only a separate Postgres-connected worker ever writes
+    (visualization/grafana/retraining_status.json) - which doesn't exist
+    in a standalone `aq backtest` run, so that condition is a live no-op
+    during backtests today. It is also a portfolio-wide sticky trade-lock
+    trip (blast radius: everything), a different kind of decision from
+    this module's book-construction-level, per-rebalance engagement veto
+    (blast radius: this one rebalance). Wiring this module's rolling
+    buffer into that kill-switch condition too would be a real, small,
+    separately-verifiable follow-up - explicitly not done here, to keep
+    this round's verification story to one mechanism.
+
+Pure, deterministic, cheap - both functions below do only pandas/numpy
+work over an already-assembled event list (no I/O), respecting main.py's
+per-bar latency budget the same way every other pure risk/analyzer module
+in this codebase does (risk/kill_switch.py, analyzer/market_analyzer.py).
+
+Design choice: a hard, boolean gate - not a continuous position-sizing
+multiplier. Every existing book-level check (min_rank_confidence_spread)
+is a hard veto with a single, audit-log-able reason, and
+book_construction.py's own docstring already defers continuous
+rank-weighted sizing as a documented future extension rather than
+building it alongside a same-round change to the selection logic itself.
+A scaling multiplier for this signal specifically is the same kind of
+future extension, deferred for the same reason: shipping a new signal and
+a new sizing curve in the same round makes it impossible to attribute a
+verification result to either one cleanly.
+"""
+
+from __future__ import annotations
+
+from evaluation.rank_ic_core import aggregate_rank_ic_observations, resolve_realized_rank_ic_observations
+
+# Same "this condition can never fire" sentinel convention as
+# risk/kill_switch.py::_NEVER_BELOW - enabling this gate must never, by
+# itself, activate an uncalibrated threshold. The real floor comes from
+# evaluation/rolling_ic_gate_calibration.py, never guessed.
+_NEVER_BELOW = -1e12
+
+
+def compute_rolling_ic_state(
+    event_buffer: list[dict],
+    *,
+    horizon_days: int,
+    rolling_window_days: int,
+    min_names_per_date: int = 2,
+) -> dict:
+    """Resolves `event_buffer` (main.py's own flat, in-memory
+    {"ticker", "created_at", "resolved_predicted_rank_20d", "close_price"}
+    deque, or the offline replay/calibration tools' equivalent) via
+    evaluation.rank_ic_core.resolve_realized_rank_ic_observations(), then
+    restricts to the trailing `rolling_window_days` UNIQUE resolved
+    origin dates (not calendar days, and not raw observation count - a
+    date with more symbols resolved must not count for more "days" of
+    trailing history than a thin one) before aggregating.
+
+    `min_names_per_date` (V5.3.5, development/Problems.md #102) - default
+    2 preserves this function's original behavior exactly (see
+    evaluation.rank_ic_core.rank_ic_from_arrays()'s own docstring for why
+    this exists: a 2-name origin date is mathematically forced to a
+    +-1 IC reading regardless of real skill, and real historical data
+    confirmed this dominates the low tail of a walk-forward calibration's
+    distribution). Callers evaluating a live or replayed rolling-IC
+    reading - where thin-universe noise masquerading as "the model is
+    badly wrong" would cause a spurious veto - should pass a value well
+    above 2 (evaluation/rolling_ic_gate_calibration.py and evaluation/
+    rolling_ic_gate_replay.py both default to 10, sourced from
+    phase_v2.rolling_ic_gate.min_names_per_date).
+
+    Returns {"rolling_mean_ic": float | None, "num_resolved_dates": int,
+    "num_resolved_observations": int}. `rolling_mean_ic` is None (never
+    0.0) when zero observations have resolved yet - "unknown" must never
+    be silently treated as "IC is exactly zero" by evaluate_rolling_ic_gate()
+    below, the same None-vs-neutral-default distinction every other pure
+    signal function in this codebase already draws (e.g.
+    risk/kill_switch.py::_rolling_sharpe())."""
+    resolved = resolve_realized_rank_ic_observations(event_buffer, horizon_days=horizon_days)
+    if not resolved:
+        return {"rolling_mean_ic": None, "num_resolved_dates": 0, "num_resolved_observations": 0}
+
+    unique_dates = sorted({observation["origin_date"] for observation in resolved})
+    trailing_dates = set(unique_dates[-rolling_window_days:]) if rolling_window_days > 0 else set()
+    trailing_observations = [observation for observation in resolved if observation["origin_date"] in trailing_dates]
+
+    if not trailing_observations:
+        return {"rolling_mean_ic": None, "num_resolved_dates": 0, "num_resolved_observations": 0}
+
+    aggregate = aggregate_rank_ic_observations(trailing_observations, min_names_per_date=min_names_per_date)
+    return {
+        "rolling_mean_ic": aggregate["mean_ic"] if aggregate["num_dates"] > 0 else None,
+        "num_resolved_dates": aggregate["num_dates"],
+        "num_resolved_observations": len(trailing_observations),
+    }
+
+
+def evaluate_rolling_ic_gate(rolling_ic_state: dict, config: dict) -> dict:
+    """Pure decision function - the direct sibling of
+    portfolio.book_construction.compute_confidence_spread()'s consumer at
+    _select_book_group(). `rolling_ic_state` is compute_rolling_ic_state()'s
+    own output; `config` is phase_v2.rolling_ic_gate's dict.
+
+    GUARDRAIL - fail-open at two levels, matching
+    risk/kill_switch.py::evaluate_kill_switch()'s own documented contract:
+      1. config["enabled"] is False -> always engaged, full no-op,
+         regardless of any other input.
+      2. num_resolved_dates < min_resolved_dates_required (default:
+         config's own rolling_window_days, matching evaluate_kill_switch()'s
+         min_bars_for_sharpe precedent - "the trailing window size" is the
+         value's own documented intent) -> also engaged. A cold-start
+         buffer (the first ~40-60 live bars of any run, before enough
+         predictions have had time to resolve against a realized 20-day
+         forward return) must never masquerade as "IC is bad" - it must
+         masquerade as "gate not evaluated yet".
+
+    Returns {"engaged": bool, "reason": str, "observed_rolling_mean_ic":
+    float | None, "min_rolling_mean_ic": float, "num_resolved_dates": int}."""
+    min_rolling_mean_ic = float(config.get("min_rolling_mean_ic", _NEVER_BELOW))
+    num_resolved_dates = int(rolling_ic_state.get("num_resolved_dates", 0))
+    observed_rolling_mean_ic = rolling_ic_state.get("rolling_mean_ic")
+
+    if not bool(config.get("enabled", False)):
+        return {
+            "engaged": True,
+            "reason": "rolling_ic_gate_disabled",
+            "observed_rolling_mean_ic": observed_rolling_mean_ic,
+            "min_rolling_mean_ic": min_rolling_mean_ic,
+            "num_resolved_dates": num_resolved_dates,
+        }
+
+    min_resolved_dates_required = int(config.get("min_resolved_dates_required", config.get("rolling_window_days", 40)))
+    if num_resolved_dates < min_resolved_dates_required or observed_rolling_mean_ic is None:
+        return {
+            "engaged": True,
+            "reason": "rolling_ic_gate_insufficient_history",
+            "observed_rolling_mean_ic": observed_rolling_mean_ic,
+            "min_rolling_mean_ic": min_rolling_mean_ic,
+            "num_resolved_dates": num_resolved_dates,
+        }
+
+    if observed_rolling_mean_ic < min_rolling_mean_ic:
+        return {
+            "engaged": False,
+            "reason": "rolling_ic_below_floor",
+            "observed_rolling_mean_ic": observed_rolling_mean_ic,
+            "min_rolling_mean_ic": min_rolling_mean_ic,
+            "num_resolved_dates": num_resolved_dates,
+        }
+
+    return {
+        "engaged": True,
+        "reason": "rolling_ic_above_floor",
+        "observed_rolling_mean_ic": observed_rolling_mean_ic,
+        "min_rolling_mean_ic": min_rolling_mean_ic,
+        "num_resolved_dates": num_resolved_dates,
+    }