quantred 2.4.0__py3-none-any.whl

quantred/portfolio/policy.py

@@ -0,0 +1,335 @@
+"""Multi-period trading: aim in front of the target.
+
+The plain single-period solve (:class:`~quantred.portfolio.optimizer.MeanVarianceOptimizer`)
+is honestly cost-aware, but it is still **myopic**: every rebalance it pays real
+cost to reach *this period's* optimum, ignoring that (1) alphas decay, so some of
+what it trades into is gone by the time it fully arrives, and (2) today's trade
+sets tomorrow's starting point, so a chain of myopic solves over-trades relative
+to the true dynamic optimum whenever alphas are persistent.
+
+With quadratic trading costs and exponentially-decaying signals, the dynamic
+program collapses to two rules:
+
+- **The aim portfolio** - the Markowitz solve on alphas *discounted* by
+  ``κ/(κ+φ)`` per signal (``φ`` its decay rate, ``κ`` the trading rate below) -
+  "aim in front of the target": construct the portfolio you'll still want once you
+  get there, not the one you want today.
+- **Partial adjustment** - trade a fraction ``κ ∈ (0,1]`` of the gap each period,
+  ``w_t = w_{t-1} + κ·(aim_t - w_{t-1})``, ``κ`` increasing in risk (urgency) and
+  decreasing in cost.
+
+This module derives ``κ`` from the book's own risk-aversion/variance and cost
+curvature (a closed form checked against limiting cases below), applies the decay
+discount, and composes the partial-adjustment step with the optimizer's own
+no-trade band via its *existing* proximal-projection machinery - it wraps
+:class:`~quantred.portfolio.optimizer.MeanVarianceOptimizer`, never modifies it. A cost
+curvature that can't be estimated (no capital, or a trade too small to pin the
+√-impact term) is not an error - the policy degrades gracefully to exactly the
+plain myopic, cost-aware solve (see :func:`derive_kappa`).
+
+**κ derivation.** Single-asset discrete-time LQ control with quadratic risk
+``λσ²w²`` and quadratic trading cost ``(c₂/2)Δw²`` (our real cost is linear +
+3/2-power; ``c₂`` is its local curvature at the book's typical trade size, see
+:func:`quantred.costs.parametric.cost_curvature` - an approximation validated by the
+net-of-cost A/B, not asserted exact). The Bellman value function
+``V(w,f) = -Aw² + Bwf - Cf²`` for a signal decaying as ``f_{t+1} = δf_t`` gives, by
+matching quadratic coefficients: ``L := λσ² + A`` solves
+``L² - λσ²·L - λσ²c₂/2 = 0``, so with ``s = λσ²``:
+
+    L = (s + √(s² + 2·s·c₂)) / 2         κ = 2L/(2L + c₂)
+
+which simplifies to the closed form in :func:`derive_kappa` - with **no dependence
+on φ** in κ itself (φ only enters the discount, below): the trading *speed*
+depends on risk/cost alone; *what you aim at* depends on decay. Limiting cases,
+both exact and tested (``test_kappa_limits``): ``c₂ → 0 ⇒ κ → 1`` (costless: no
+curvature to solve against - see the fallback note below); ``c₂ → ∞ ⇒ κ → 0``;
+monotone (``∂κ/∂c₂ < 0`` for all ``c₂ ≥ 0``) ⇒ κ increasing in ``s = λ_A·σ²``,
+decreasing in cost.
+
+Solving the *other* coefficient-matching equation (the ``B``/``wf`` coefficient)
+exactly - using the algebraic identity ``2Lθ = c₂·a`` that falls out of the same
+fixed point - gives the *aim* coefficient (the weight on ``f`` in the optimal
+policy) **exactly**: ``μ/a = a / [2λσ²·(1 − δ(1−a))]`` where ``δ = e^(−φ)`` is the
+per-rebalance persistence - i.e. the discount on alpha is ``κ / (1 − δ(1−κ))``
+(:func:`discount_factor`), not merely its small-φ limit ``κ/(κ+φ)`` (which is
+what a first pass at this derivation gives, and is commonly quoted this way, but
+whose error *grows* with φ - a real bug in an earlier draft of this module,
+caught by ``test_synthetic_gp_world...`` disagreeing with a direct value-
+iteration solve of the Bellman recursion at large φ). Since the exact form costs
+nothing extra to evaluate, :func:`discount_factor` uses it directly.
+
+**Why "costless ⇒ exact myopic" is a fallback, not a limit.** Plugging ``c₂ = 0``
+into the closed form gives ``κ = 1`` exactly, and at ``κ=1`` the exact discount
+formula above *does* correctly give 1 (``δ(1−1) = 0``) for any φ - so the
+costless case is consistent either way here. The fallback is still needed for a
+different reason: :func:`derive_kappa` has no way to fit ``c₂`` at all without an
+impact term (no capital, or a linear-only cost model) - "undefined" is not the
+same number as "zero", and treating it as zero would silently invent a κ=1 from
+a curvature that was never actually measured. So the policy's job is to
+recognize "no curvature to fit" and hand
+back the exact myopic solve, undiscounted, rather than apply a discount formula
+whose derivation assumed a nonzero cost. :func:`derive_kappa` returns ``None``
+whenever the cost curvature is undefined (no impact term, or too small a typical
+trade to pin it), and :func:`build_aim_portfolio` treats ``None`` as "run the
+plain solve exactly, band-only" - this is what makes the costless limiting case
+an *exact*, tested reduction (``test_costless_reduces_to_exact_myopic``) instead of an asymptote.
+"""
+
+import math
+from dataclasses import replace
+from typing import Dict, List, Optional
+
+import numpy as np
+
+from quantred.alphas.base import Alpha
+from quantred.portfolio.optimizer import MeanVarianceOptimizer, PortfolioResult
+from quantred.risk.base import RiskMatrix
+
+#: Floor on the typical per-name trade size fed to the curvature fit -
+#: avoids a near-zero denominator manufacturing an absurd κ when the myopic
+#: reference solve traded almost nothing (e.g. it was already near its no-trade band).
+MIN_TYPICAL_TRADE = 1e-4
+
+
+# --------------------------------------------------------------------------- #
+# Pure math: decay units, the discount, and the trading rate κ
+# --------------------------------------------------------------------------- #
+def phi_from_half_life(half_life_periods: float, min_half_life: float = 1.0) -> float:
+    """Per-rebalance decay rate ``φ = ln2 / HL``, floored at ``min_half_life``
+    (can't measure decay faster than the rebalance frequency itself - a floor of
+    1 rebalance is the fastest a half-life can mean anything).
+    A permanent signal (``HL = inf``) has ``φ = 0`` - no discount at any κ.
+    """
+    if not math.isfinite(half_life_periods):
+        return 0.0
+    return math.log(2) / max(half_life_periods, min_half_life)
+
+
+def half_life_in_rebalance_units(half_life_periods: float, periods_per_rebalance: float) -> float:
+    """Convert a half-life measured in raw bars into rebalance units - silently
+    mixing bars and rebalances would misprice every discount by the cadence
+    factor. ``periods_per_rebalance`` is the bar count between rebalances (e.g.
+    ~21 for a monthly cadence on daily bars). A non-finite half-life (permanent
+    signal) or a non-positive cadence passes through unchanged.
+    """
+    if not math.isfinite(half_life_periods) or periods_per_rebalance <= 0:
+        return half_life_periods
+    return half_life_periods / periods_per_rebalance
+
+
+def discount_factor(kappa: float, phi: float) -> float:
+    """The aim-alpha decay discount, the **exact** closed form:
+
+        discount = κ / (1 − δ·(1−κ)),   δ = e^(−φ)
+
+    (derived from the same Riccati fixed point as :func:`derive_kappa` - see the
+    module docstring - by solving the *other* coefficient-matching equation,
+    ``B(1−δθ) = θ·β``, exactly, with no small-φ linearization). This is
+    numerically verified against a direct value-iteration solve of the Bellman
+    recursion (see ``test_discount_factor_matches_value_iteration``): the
+    frequently-quoted ``κ/(κ+φ)`` form is only this formula's small-φ limit
+    (``δ ≈ 1−φ`` ⇒ ``1−δ(1−κ) ≈ φ+κ``) and its error *grows* with φ - exact is no
+    more expensive to compute, so there is no reason to use the approximation.
+
+    ``φ = 0`` (a permanent signal) ⇒ ``δ = 1`` ⇒ discount ``= 1`` at any κ,
+    exactly - no discount ever applies to a signal that doesn't decay. ``κ → 0``
+    (trading nearly frozen) ⇒ discount ``→ κ/(1−δ)`` for any φ > 0, which
+    coincides with the familiar ``κ/φ`` in the same small-φ limit.
+    """
+    if phi <= 0:
+        return 1.0
+    if kappa <= 0:
+        return 0.0
+    delta = math.exp(-phi)
+    denom = 1.0 - delta * (1.0 - kappa)
+    return kappa / denom if denom > 0 else 1.0
+
+
+def derive_kappa(risk_aversion: float, variance: float, cost_curvature: Optional[float]) -> Optional[float]:
+    """Gârleanu-Pedersen's trading rate, closed form (derived in this module's
+    docstring): ``s = λ_A·σ²``, ``κ = (s + √(s²+2sc₂)) / (s + c₂ + √(s²+2sc₂))``.
+
+    Monotone increasing in ``s`` (risk/urgency), decreasing in ``c₂`` (cost
+    curvature) - ``test_kappa_monotonicity`` grids this. ``κ → 1`` as ``c₂ → 0``;
+    ``κ → 0`` as ``c₂ → ∞`` (``test_kappa_limits``).
+
+    Returns ``None`` - the "cost curvature ill-defined" signal - when ``c₂`` is
+    missing/non-positive (no impact term, or a trade too small to pin it) or when
+    ``risk_aversion·variance`` itself is non-positive. The caller
+    (:func:`build_aim_portfolio`) treats ``None`` as "fall back to the plain
+    myopic solve exactly, band-only" (a documented fallback), not an error.
+    """
+    if cost_curvature is None or not (cost_curvature > 0):
+        return None
+    s = risk_aversion * variance
+    if not (s > 0):
+        return None
+    root = math.sqrt(s * s + 2.0 * s * cost_curvature)
+    return (s + root) / (s + cost_curvature + root)
+
+
+def trading_half_life(kappa: float) -> float:
+    """Implied trading half-life, in rebalances: ``ln2/κ`` - a reported
+    diagnostic. Infinite when κ is non-positive (frozen book)."""
+    return math.log(2) / kappa if kappa > 0 else float("inf")
+
+
+# --------------------------------------------------------------------------- #
+# The policy: aim construction + partial adjustment, wrapping the optimizer
+# --------------------------------------------------------------------------- #
+def build_aim_portfolio(
+    optimizer: MeanVarianceOptimizer,
+    alphas: List[Alpha],
+    risk: RiskMatrix,
+    *,
+    phi: float = 0.0,
+    trade_rate: Optional[float] = None,
+    target_te: Optional[float] = None,
+    risk_aversion: Optional[float] = None,
+    current_weights: Optional[Dict[str, float]] = None,
+    cost_model=None,
+    cost_inputs=None,
+    capital: Optional[float] = None,
+    holding_period_years: float = 1.0 / 12.0,
+) -> PortfolioResult:
+    """The aim-in-front-of-the-target policy: derive κ, discount the alphas by
+    ``κ/(κ+φ)``, solve the cost-free aim (the plain optimizer with the cost term
+    zeroed), take the κ-fraction step from ``current_weights``, and pass the
+    result through the optimizer's own proximal band projection (the *same*
+    box/budget/no-trade-band machinery a real cost-aware solve would apply -
+    reused via :meth:`MeanVarianceOptimizer._prox_project`, never re-derived) so
+    the band and κ compose rather than stack independently.
+
+    ``phi`` is the (already per-rebalance, already CI-adjusted) decay rate for
+    this alpha vector - a single scalar, since v1 is a single combined signal per
+    call (scalar κ/φ is the v1 lean; per-signal only matters upstream of
+    multi-signal combination, where :func:`discount_factor` is the same one-line
+    vector scale applied per signal before ``combine_scores`` - no change needed
+    here).
+
+    ``trade_rate`` overrides the derived κ (the CLI's ``--trade-rate``). Without a
+    usable cost curvature (no capital, or the myopic reference solve traded too
+    little to pin one) and no override, this **falls back to exactly the plain
+    cost-aware solve** - the costless/undefined-curvature reduction is exact,
+    not asymptotic (see the module docstring). Position constraints (box,
+    cardinality, min-weight) are enforced on the *aim* solve itself (it is a full
+    solve), so the final κ-adjusted-and-banded trade then respects the box via
+    the proximal projection, though a rebalance whose ``current_weights`` and
+    aim disagree sharply on *which* names to hold can, in principle, transiently
+    exceed ``max_names`` until the next full re-solve (a documented v1
+    limitation, not exercised when ``max_names`` is unset).
+
+    Book scope: **long-only only** in v1 (the final banding step reuses the
+    long-only proximal projection). Benchmark-relative books are also out of
+    v1's scope - the aim/myopic split here works in cash-relative space only.
+    """
+    myopic = optimizer.optimize(
+        alphas,
+        risk,
+        target_te=target_te,
+        risk_aversion=risk_aversion,
+        current_weights=current_weights,
+        cost_model=cost_model,
+        cost_inputs=cost_inputs,
+        capital=capital,
+        holding_period_years=holding_period_years,
+    )
+    if not myopic.feasible:
+        return myopic
+
+    symbols, alpha_vec = MeanVarianceOptimizer._align(alphas, risk)
+    if len(symbols) == 0:
+        return myopic
+
+    sigma = MeanVarianceOptimizer._submatrix(risk, symbols)
+    lam = float(myopic.diagnostics["risk_aversion"])
+    c_lin, k_imp = MeanVarianceOptimizer._cost_coefficients(
+        cost_model, cost_inputs, capital, holding_period_years, symbols
+    )
+
+    names_traded = myopic.diagnostics.get("names_traded")
+    turnover = float(myopic.diagnostics.get("turnover", 0.0))
+    typical_trade = (turnover / names_traded) if names_traded else MIN_TYPICAL_TRADE
+    typical_trade = max(typical_trade, MIN_TYPICAL_TRADE)
+
+    mean_k = float(np.mean(k_imp)) if k_imp.size else 0.0
+    typical_variance = float(np.mean(np.diag(sigma)))
+    from quantred.costs.parametric import cost_curvature
+
+    c2 = cost_curvature(mean_k, typical_trade)
+    kappa_derived = derive_kappa(lam, typical_variance, c2)
+    kappa = trade_rate if trade_rate is not None else kappa_derived
+
+    if kappa is None or not (kappa > 0):
+        result = PortfolioResult(
+            weights=dict(myopic.weights),
+            feasible=True,
+            binding_constraint=myopic.binding_constraint,
+            diagnostics={
+                **myopic.diagnostics,
+                "policy": "myopic_fallback",
+                "aim_degraded": True,
+                "fallback_reason": "cost curvature undefined (no capital/impact term, or "
+                "trade too small to pin c2) and no --trade-rate override; degraded to "
+                "the plain cost-aware solve",
+                "cost_curvature": c2,
+                "kappa_derived": kappa_derived,
+                "typical_trade_size": typical_trade,
+            },
+            unconstrained_weights=dict(myopic.unconstrained_weights),
+        )
+        return result
+
+    discount = discount_factor(kappa, phi)
+    discounted_alphas = [replace(a, alpha=a.alpha * discount) for a in alphas]
+
+    aim = optimizer.optimize(
+        discounted_alphas,
+        risk,
+        risk_aversion=lam,
+        current_weights=current_weights,
+        cost_model=None,
+        cost_inputs=None,
+        capital=None,
+    )
+    if not aim.feasible:
+        return aim
+
+    w_prev = MeanVarianceOptimizer._vector(current_weights or {}, symbols)
+    w_aim = MeanVarianceOptimizer._vector(aim.weights, symbols)
+    raw_target = w_prev + kappa * (w_aim - w_prev)
+
+    lmax = float(np.linalg.eigvalsh(sigma).max())
+    step = 1.0 / (2.0 * lam * lmax) if lmax > 0 else 1.0
+    thr = step * c_lin
+    kthr = step * k_imp
+    w_final = optimizer._prox_project(raw_target, thr, kthr, w_prev)
+
+    sigma_inv = np.linalg.inv(sigma)
+    ir_star = float(np.sqrt(max(alpha_vec @ sigma_inv @ alpha_vec, 0.0)))
+    zeros = np.zeros(len(symbols))
+    cost_aware = bool(np.any(c_lin > 0) or np.any(k_imp > 0))
+    diagnostics = optimizer._diagnostics(
+        alpha_vec, sigma, w_final, w_prev, lam, ir_star, c_lin, k_imp, cost_aware, zeros, zeros, 0.0
+    )
+    diagnostics.update(
+        {
+            "policy": "aim",
+            "aim_degraded": False,
+            "kappa": kappa,
+            "kappa_derived": kappa_derived,
+            "kappa_overridden": trade_rate is not None,
+            "trading_half_life_rebalances": trading_half_life(kappa),
+            "cost_curvature": c2,
+            "typical_trade_size": typical_trade,
+            "phi_per_rebalance": phi,
+            "signal_discount": discount,
+        }
+    )
+
+    return PortfolioResult(
+        weights={s: float(w_final[i]) for i, s in enumerate(symbols) if abs(w_final[i]) > 1e-9},
+        feasible=True,
+        diagnostics=diagnostics,
+        unconstrained_weights=dict(aim.weights),
+    )

quantred/portfolio/posterior.py

@@ -0,0 +1,208 @@
+"""Black–Litterman posterior: blend our views with Σ's implied propagation.
+
+The reverse-optimized consensus (``quantred/portfolio/benchmark.py``) backs out the
+expected returns for which the benchmark is itself optimal; our alphas are
+*deviations from* that consensus. Left alone, the optimizer reads a name with no
+signal as a *hard* zero-view ("this name earns exactly consensus") rather than as
+ignorance, and treats every view's confidence as baked into its magnitude alone.
+Black–Litterman fixes both: a single precision-weighted blend of the (zero, in
+residual space) prior and our views, where prior precision comes from ``(τΣ)⁻¹``
+and view precision from measured IC. Names we never scored still get a real,
+nonzero posterior when they're correlated with a name we *did* score ("never zero
+the correlated forecasts") — the propagation is the entire point.
+
+Pure numpy, no I/O. Two layers:
+
+- :func:`black_litterman` — the update itself, given ``Ω`` directly (a diagonal
+  view-covariance dict). This is the primitive the limit tests (Ω→0, Ω→∞) drive.
+- :func:`black_litterman_from_ic` — derives ``Ω`` from IC via the calibration
+  identity (:func:`view_variance`) and calls the primitive. This is what
+  ``construct_portfolio`` calls.
+
+Everything here is in **residual/active space**: the prior mean is exactly 0, not
+because our alphas happen to be benchmark-neutral, but because the
+reverse-optimization consensus is *defined* as the return explained by beta — by
+construction there is zero consensus residual return left over. ``q`` (the views)
+must be the *unshrunk* refined alphas (the refinement's own level-shrink stage
+left off upstream) — Ω below already carries the full IC-uncertainty haircut, so
+shrinking twice would halve it twice.
+"""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+import numpy as np
+
+from quantred.alphas.refine import level_shrink_factor
+from quantred.risk.base import RiskMatrix
+
+
+@dataclass
+class BLPosterior:
+    """The BL posterior over Σ's full universe, plus the audit trail (τ-sensitivity, sourcing)."""
+
+    mu_post: Dict[str, float]  # symbol -> posterior residual return, EVERY Σ symbol
+    source: Dict[str, str]  # symbol -> "view" | "propagated" | "prior"
+    views: Dict[str, float] = field(default_factory=dict)  # symbol -> q, covered names only
+    omega: Dict[str, float] = field(default_factory=dict)  # symbol -> view variance, covered only
+    tau: float = 0.0
+    tau_sensitivity: Dict[str, Dict[str, float]] = field(default_factory=dict)
+    #: Set only by :func:`black_litterman_from_ic` (the low-level update takes Ω
+    #: directly and has no notion of a single IC/T_eff behind it).
+    ic: Optional[float] = None
+    t_eff: Optional[float] = None
+
+
+def view_variance(residual_vol: float, ic: float, t_eff: float) -> float:
+    """The calibration-forced view-error variance ``Ω_n = ω_n² / (T_eff²·IC²)``.
+
+    Not the naive ``ω²·(1−IC²)`` — that formula alone prices only "the signal
+    isn't perfectly correlated with truth," and ignores that IC itself is
+    *estimated* over a finite ``T_eff``. The calibration identity (a single
+    covered-name view, uninformative prior, pinned ``τ = 1/T_eff``, must reproduce
+    the refinement's own level-shrunk alpha exactly — the ``g/(g+1)`` weight
+    :func:`~quantred.alphas.refine.level_shrink_factor` already computes, ``g =
+    T_eff·IC²``) forces this closed form: the BL blend weight on a single view is
+    ``τω²/(τω²+Ω)``; setting that equal to ``g/(g+1)`` with ``τ = 1/T_eff`` and
+    solving for ``Ω`` gives exactly ``ω²/(T_eff²·IC²)``.
+
+    Returns ``inf`` when ``ic`` is zero/non-finite or ``t_eff`` is non-positive (an
+    uninformative view carries zero precision, i.e. infinite variance) — callers
+    that build a diagonal Ω matrix must drop such views rather than pass ``inf``
+    through a linear solve (see :func:`black_litterman_from_ic`).
+    """
+    if not np.isfinite(ic) or ic == 0 or t_eff <= 0:
+        return float("inf")
+    return float((residual_vol**2) / (t_eff**2 * ic**2))
+
+
+def expected_single_view_weight(ic: float, t_eff: float) -> float:
+    """The blend weight a lone covered-name view must land on (the calibration identity).
+
+    Reuses :func:`~quantred.alphas.refine.level_shrink_factor` directly (not a second,
+    independently-derived formula) so the calibration test is a tautology by
+    construction if :func:`view_variance` is right, and a real check if it isn't.
+    """
+    return level_shrink_factor(ic, t_eff)
+
+
+def calibration_gap(posterior: "BLPosterior") -> Optional[float]:
+    """For a single-view posterior, ``actual_weight − expected_weight``.
+
+    ``actual_weight = μ_post,n / q_n`` for the one covered name; ``expected_weight``
+    is :func:`expected_single_view_weight`. Near 0 is the pass condition — anything
+    else means Ω is mis-derived relative to the refinement's level shrink (double- or
+    under-shrunk). Returns ``None`` when the posterior isn't single-view (the K=N
+    matrix-form generalization of this same identity is a future extension) or
+    when ``ic``/``t_eff`` weren't recorded (a raw :func:`black_litterman` call).
+    """
+    if len(posterior.views) != 1 or posterior.ic is None or posterior.t_eff is None:
+        return None
+    ((sym, q),) = posterior.views.items()
+    if q == 0:
+        return None
+    actual = posterior.mu_post[sym] / q
+    expected = expected_single_view_weight(posterior.ic, posterior.t_eff)
+    return float(actual - expected)
+
+
+def black_litterman(
+    views: Dict[str, float],
+    risk: RiskMatrix,
+    omega: Dict[str, float],
+    tau: float,
+) -> BLPosterior:
+    """The BL update in residual/active space:
+    ``μ_post = τΣPᵀ(PτΣPᵀ+Ω)⁻¹q``.
+
+    Zero-prior-mean, one ``(K×K)`` solve (``K`` = number of covered names — cheap at
+    this scale). ``views`` (``q``) and ``omega`` (``Ω``, diagonal, one entry per
+    view — exactly one view per name, already decorrelated/combined upstream by
+    the multi-signal combination) are keyed by symbol; any symbol in ``views``
+    absent from ``risk.symbols`` is ignored. Also computes the τ-sensitivity
+    (posterior recomputed at ``τ/2`` and ``2τ``).
+    """
+    symbols = list(risk.symbols)
+    idx = {s: i for i, s in enumerate(symbols)}
+    sigma = risk.sigma
+
+    covered = [s for s in views if s in idx and s in omega]
+    cov_idx = [idx[s] for s in covered]
+    q = np.array([views[s] for s in covered], dtype=float)
+    omega_diag = np.array([omega[s] for s in covered], dtype=float)
+
+    tau_eff = max(float(tau), 0.0)
+    mu_post_vec = _update(sigma, cov_idx, q, omega_diag, tau_eff)
+
+    tol = 1e-12
+    source: Dict[str, str] = {}
+    for s in symbols:
+        if s in covered:
+            source[s] = "view"
+        elif abs(mu_post_vec[idx[s]]) > tol:
+            source[s] = "propagated"
+        else:
+            source[s] = "prior"
+
+    sensitivity: Dict[str, Dict[str, float]] = {}
+    for label, t in (("tau_half", tau_eff / 2.0), ("tau_double", tau_eff * 2.0)):
+        vec = _update(sigma, cov_idx, q, omega_diag, t)
+        sensitivity[label] = {s: float(vec[idx[s]]) for s in symbols}
+
+    return BLPosterior(
+        mu_post={s: float(mu_post_vec[idx[s]]) for s in symbols},
+        source=source,
+        views={s: float(views[s]) for s in covered},
+        omega={s: float(omega[s]) for s in covered},
+        tau=tau_eff,
+        tau_sensitivity=sensitivity,
+    )
+
+
+def black_litterman_from_ic(
+    views: Dict[str, float],
+    risk: RiskMatrix,
+    ic: float,
+    t_eff: float,
+    tau: Optional[float] = None,
+) -> BLPosterior:
+    """:func:`black_litterman` with Ω derived from IC and τ pinned to
+    ``1/T_eff`` — what ``construct_portfolio`` calls.
+
+    A view whose derived Ω is non-finite (``ic`` zero/non-finite, or ``t_eff`` ≤ 0 —
+    an uninformative signal or unmeasurable sample) is dropped from the covered set
+    entirely rather than passed through as ``inf`` (which would poison the linear
+    solve); its name still gets a posterior, either 0 (prior) or a nonzero
+    propagated value from OTHER views, exactly as if it had never had a signal.
+    """
+    symbols = list(risk.symbols)
+    idx = {s: i for i, s in enumerate(symbols)}
+    filtered_views: Dict[str, float] = {}
+    omega: Dict[str, float] = {}
+    for s, q in views.items():
+        if s not in idx or q != q:  # not covered by Σ, or NaN
+            continue
+        vol = float(np.sqrt(max(risk.sigma[idx[s], idx[s]], 0.0)))
+        om = view_variance(vol, ic, t_eff)
+        if np.isfinite(om):
+            filtered_views[s] = q
+            omega[s] = om
+
+    tau_eff = float(tau) if tau is not None else (1.0 / t_eff if t_eff > 0 else 0.0)
+    posterior = black_litterman(filtered_views, risk, omega, tau_eff)
+    posterior.ic = float(ic)
+    posterior.t_eff = float(t_eff)
+    return posterior
+
+
+def _update(
+    sigma: np.ndarray, cov_idx: List[int], q: np.ndarray, omega_diag: np.ndarray, tau: float
+) -> np.ndarray:
+    """``μ_post = τΣPᵀ(PτΣPᵀ+Ω)⁻¹q`` for one ``τ`` — the shared inner solve."""
+    n = sigma.shape[0]
+    if not cov_idx:
+        return np.zeros(n)
+    tau_sigma_pt = tau * sigma[:, cov_idx]  # (n x K): τΣPᵀ
+    m = tau_sigma_pt[cov_idx, :] + np.diag(omega_diag)  # (K x K): PτΣPᵀ + Ω
+    x = np.linalg.solve(m, q)
+    return tau_sigma_pt @ x

quantred/research/__init__.py

@@ -0,0 +1,30 @@
+"""Autonomous research agent (opt-in behind the ``ai`` extra).
+
+A bounded, offline research loop: propose a hypothesis -> express it as a config
+(or, behind a flag, as new strategy code) -> validate it out-of-sample with
+walk-forward -> keep/discard -> repeat until budget or dryness -> score the
+survivors once on the sacred holdout -> hand a human a shortlist.
+
+The agent reuses the *same* :mod:`quantred.services` core as the MCP server, so there
+is one code path. It never touches live trading, never toggles ``PAPER_TRADE``,
+and is scored exclusively on out-of-sample output (see :mod:`quantred.research.agent`
+for the non-negotiable guardrails). The proposer is provider-agnostic - Claude,
+OpenAI, or a local Ollama model (see :mod:`quantred.research.llm`).
+"""
+
+from quantred.research.agent import Candidate, ResearchAgent, ResearchConfig, ResearchResult
+from quantred.research.llm import build_llm_client
+from quantred.research.proposer import FixedProposer, LLMProposer, Proposal, Proposer, build_proposer
+
+__all__ = [
+    "ResearchAgent",
+    "ResearchConfig",
+    "ResearchResult",
+    "Candidate",
+    "Proposer",
+    "Proposal",
+    "FixedProposer",
+    "LLMProposer",
+    "build_proposer",
+    "build_llm_client",
+]