quantred 2.4.0__py3-none-any.whl

quantred/research/sandbox.py

@@ -0,0 +1,340 @@
+"""Validation sandbox for proposals - the rules that keep an eager AI from
+manufacturing overfit garbage at scale (its words would be more enthusiastic).
+
+Two jobs:
+
+1. **Research-hygiene gates** on every proposal: a rationale must be present, and
+   no more than :data:`MAX_TUNABLE_PARAMS` parameters may be varied. These are the
+   cheap, load-bearing rules that stop the loop manufacturing overfit garbage at
+   scale.
+2. **Contract validation** of agent-authored strategy/scanner *code*: a strategy
+   must define a concrete :class:`~quantred.strategies.base.Strategy` subclass that
+   implements the abstract hooks, declares a valid ``PARAM_RANGES`` (<= 5
+   searchable), carries a docstring (the hypothesis), and actually constructs. A
+   scanner must define a concrete :class:`~quantred.scanners.base.ScannerStrategy`
+   subclass that emits the scanner signal vocabulary and a numeric
+   ``signal_strength``.
+
+Isolation note: generated code is validated and executed with a restricted global
+namespace (no ``os``/``sys``/network imports, limited builtins). This is a
+*proposal artifact*, never auto-merged. True OS-level isolation (separate process,
+no network, resource limits) is the production hardening called for in  and is
+left as a deliberate follow-up; :func:`load_strategy_from_code` and
+:func:`load_scanner_from_code` are the choke points where that would be enforced.
+"""
+
+import builtins as _builtins
+from collections.abc import Mapping
+from typing import Optional, Tuple, Type
+
+from quantred.optimization.param_space import ParameterSpace
+from quantred.scanners.base import SCANNER_BUY, SCANNER_HOLD, SCANNER_SELL, ScannerStrategy
+from quantred.strategies.base import Strategy
+
+#: Hard cap on tunable parameters per strategy (more knobs = more overfit surface).
+MAX_TUNABLE_PARAMS = 5
+
+#: Config keys the execution path reads off every strategy, regardless of mechanism:
+#: ``calculate_position_size`` needs the first two, and the backtest engine and live
+#: trader both read ``take_profit`` when opening a position. A generated strategy that
+#: omits them passes every other check and then raises on the first bar - producing a
+#: zero-trade run that is indistinguishable from "no edge" unless we catch it here.
+REQUIRED_CONFIG_KEYS = ("risk_per_trade", "stop_loss", "take_profit")
+
+#: Import names generated strategy/scanner code is allowed to use.
+#:
+#: The list exists to keep generated code away from the filesystem, the process, the
+#: network and the broker. ``typing`` and ``collections.abc`` reach none of those -
+#: they are annotation vocabulary and grant no capability - and leaving them off
+#: rejected every strategy and scanner this package ships, since all of them annotate
+#: their ``PARAM_RANGES``. A validator that refuses the repository's own examples is
+#: measuring its allowlist, not the draft.
+_ALLOWED_IMPORTS = {
+    "pandas",
+    "numpy",
+    "math",
+    "typing",
+    "collections.abc",
+    "quantred.indicators.indicators",
+    "quantred.indicators",
+    "quantred.scanners.base",
+    "quantred.scanners",
+    "quantred.strategies.base",
+    "quantred.strategies.signals",
+    "quantred.strategies",
+}
+
+#: Builtins denied to generated code (no filesystem / process / eval surface).
+_DENIED_BUILTINS = {
+    "open",
+    "exec",
+    "eval",
+    "compile",
+    "__import__",
+    "input",
+    "globals",
+    "locals",
+    "vars",
+    "memoryview",
+}
+
+
+class HygieneError(ValueError):
+    """A proposal violated a research-hygiene rule."""
+
+
+def validate_hygiene(proposal, strategy_cls: Optional[Type[Strategy]] = None) -> Tuple[bool, str]:
+    """Check a proposal against the hygiene rules; return ``(ok, reason)``.
+
+    Never raises - the caller journals the reason and skips the proposal.
+    """
+    if not (proposal.hypothesis or "").strip():
+        return False, "missing hypothesis (rationale required before evaluation)"
+
+    if proposal.kind == "tune":
+        if strategy_cls is None:
+            return False, "tune proposal without a known strategy class"
+        if not isinstance(proposal.params, Mapping):
+            return False, f"params must be an object of name: value, got {type(proposal.params).__name__}"
+        tuned = proposal.tuned_params or list(proposal.params)
+        if len(tuned) > MAX_TUNABLE_PARAMS:
+            return False, f"{len(tuned)} tuned params exceeds the cap of {MAX_TUNABLE_PARAMS}"
+        ranges = strategy_cls.PARAM_RANGES
+        for name, value in proposal.params.items():
+            if name not in ranges:
+                return False, f"unknown parameter {name!r}"
+            reason = _value_problem(name, value, ranges[name])
+            if reason:
+                return False, reason
+        return True, "ok"
+
+    if proposal.kind == "code":
+        if not isinstance(proposal.code, str) or not proposal.code.strip():
+            return False, "code proposal without source"
+        return True, "ok"
+
+    return False, f"unknown proposal kind {proposal.kind!r}"
+
+
+def _value_problem(name: str, value, spec) -> Optional[str]:
+    """Why ``value`` cannot be this parameter's value, or ``None`` when it can.
+
+    The declared type is checked before the range: ``10.5`` for an integer parameter
+    used to be evaluated and saved as ``10.5``, while ``True`` (a bool is an ``int`` to
+    Python) was reported as "outside the range" - a wrong reason that hid the real one.
+    """
+    if not isinstance(spec, Mapping):
+        return None
+    declared = spec.get("type")
+    if not (declared in ("int", "float") or ("min" in spec and "max" in spec)):
+        return None
+    expected = declared or "a number"
+    if isinstance(value, bool):
+        return f"{name}={value} is a boolean; expected {expected}"
+    if not isinstance(value, (int, float)):
+        return f"{name}={value!r} is not a number; expected {expected}"
+    if declared == "int" and isinstance(value, float) and not value.is_integer():
+        return f"{name}={value} is not an integer; {name} is declared int"
+    if "min" in spec and "max" in spec and not (spec["min"] <= value <= spec["max"]):
+        return f"{name}={value} outside [{spec['min']}, {spec['max']}]"
+    return None
+
+
+def load_strategy_from_code(code: str, *, class_name: Optional[str] = None) -> Type[Strategy]:
+    """Compile generated source and return its validated ``Strategy`` subclass.
+
+    Raises :class:`HygieneError` if the code imports disallowed modules, fails the
+    abstract-method contract, declares > 5 searchable params, lacks a docstring,
+    or does not construct from its declared defaults.
+    """
+    cls = _load_class_from_code(code, Strategy, "strategy", class_name)
+    _validate_strategy_contract(cls)
+    return cls
+
+
+def load_scanner_from_code(code: str, *, class_name: Optional[str] = None) -> Type[ScannerStrategy]:
+    """Compile generated source and return its validated ``ScannerStrategy`` subclass.
+
+    Raises :class:`HygieneError` if the code imports disallowed modules, fails the
+    abstract-method contract, declares too many searchable params, lacks a docstring,
+    or does not emit a scanner signal frame on sample OHLCV data.
+    """
+    cls = _load_class_from_code(code, ScannerStrategy, "scanner", class_name)
+    _validate_scanner_contract(cls)
+    return cls
+
+
+def _load_class_from_code(code: str, base_cls: Type, label: str, class_name: Optional[str] = None) -> Type:
+    namespace: dict = {"__builtins__": _restricted_builtins()}
+    namespace["__import__"] = _guarded_import
+    try:
+        compiled = compile(code, f"<generated-{label}>", "exec")
+        exec(compiled, namespace)  # noqa: S102 - restricted namespace, validated below
+    except Exception as exc:  # noqa: BLE001 - any failure is a rejection, not a crash
+        raise HygieneError(f"generated code failed to import: {exc}") from exc
+
+    candidates = [
+        obj
+        for obj in namespace.values()
+        if isinstance(obj, type) and issubclass(obj, base_cls) and obj is not base_cls
+    ]
+    if class_name:
+        candidates = [c for c in candidates if c.__name__ == class_name]
+    if not candidates:
+        raise HygieneError(f"no concrete {base_cls.__name__} subclass defined")
+    return candidates[-1]
+
+
+def _validate_common_contract(cls: Type, base_name: str) -> None:
+    if getattr(cls, "__abstractmethods__", None):
+        raise HygieneError(
+            f"{cls.__name__} leaves abstract methods unimplemented: {sorted(cls.__abstractmethods__)}"
+        )
+    if not (cls.__doc__ or "").strip():
+        raise HygieneError(f"{cls.__name__} has no docstring (the hypothesis is required)")
+    if not isinstance(getattr(cls, "PARAM_RANGES", None), dict):
+        raise HygieneError(f"{cls.__name__} must declare a PARAM_RANGES dict")
+    # Every rejection leaves here as a HygieneError, including a malformed spec.
+    # `PARAM_RANGES = {"lookback": 20}` is what generated code actually writes, and
+    # reading it raised a bare TypeError out of ParameterSpace - through validators
+    # whose entire contract is to answer "is this valid?" with a verdict.
+    for param, spec in cls.PARAM_RANGES.items():
+        if not isinstance(spec, Mapping):
+            raise HygieneError(
+                f"{cls.__name__} parameter {param!r} must be a spec mapping with "
+                f"min/max/step/default, not a bare {type(spec).__name__}"
+            )
+    try:
+        space = ParameterSpace.for_class(cls)
+    except ValueError as exc:
+        # Same contract as the malformed-spec rejection above: a validator whose whole
+        # job is to answer "is this valid?" must answer it, not raise something else.
+        # A draft can declare constraints, and a constraint naming a parameter that
+        # does not exist is exactly the kind of thing generated code writes.
+        raise HygieneError(f"{cls.__name__} declares an unusable PARAM_CONSTRAINTS: {exc}") from exc
+    if len(space.searchable) > MAX_TUNABLE_PARAMS:
+        # Deliberately stricter than the curated strategies this package ships: a
+        # draft is an unreviewed proposal, and knobs are overfit surface. Two shipped
+        # strategies exceed it, which is why the shipped-artifact test below admits
+        # this one rejection and no other.
+        raise HygieneError(
+            f"{cls.__name__} has {len(space.searchable)} searchable params "
+            f"(draft {base_name} cap is {MAX_TUNABLE_PARAMS})"
+        )
+
+
+def _defaults(cls: Type) -> dict:
+    return {name: spec["default"] for name, spec in cls.PARAM_RANGES.items() if "default" in spec}
+
+
+def _validate_strategy_contract(cls: Type[Strategy]) -> None:
+    _validate_common_contract(cls, "strategy")
+    # Must construct from its own defaults.
+    defaults = _defaults(cls)
+    defaults.setdefault("timeframe", getattr(cls, "TIMEFRAME", "1Day"))
+    try:
+        instance = cls(dict(defaults))
+    except Exception as exc:  # noqa: BLE001
+        raise HygieneError(f"{cls.__name__} does not construct from defaults: {exc}") from exc
+
+    # Sizing and exit handling read these off the config on every bar. Missing keys
+    # would surface as a silent zero-trade run, not an error, so reject here instead.
+    missing = [key for key in REQUIRED_CONFIG_KEYS if key not in instance.config]
+    if missing:
+        raise HygieneError(
+            f"{cls.__name__} does not declare required config {missing} "
+            f"(the execution path reads {list(REQUIRED_CONFIG_KEYS)} on every bar)"
+        )
+
+
+def _validate_scanner_contract(cls: Type[ScannerStrategy]) -> None:
+    _validate_common_contract(cls, "scanner")
+    try:
+        instance = cls(_defaults(cls))
+        instance.initialize()
+    except Exception as exc:  # noqa: BLE001
+        raise HygieneError(f"{cls.__name__} does not construct from defaults: {exc}") from exc
+
+    import pandas as pd
+
+    sample = _scanner_sample(cls, instance)
+    try:
+        signals = instance.generate_signals_df(instance.process_data(sample))
+    except Exception as exc:  # noqa: BLE001
+        raise HygieneError(f"{cls.__name__} cannot produce scanner signals on sample data: {exc}") from exc
+    required = {"signal", "signal_strength"}
+    if not required <= set(signals.columns):
+        raise HygieneError(f"{cls.__name__} scanner signals must include {sorted(required)}")
+    valid_signals = {SCANNER_BUY, SCANNER_SELL, SCANNER_HOLD}
+    emitted = set(signals["signal"].dropna())
+    if not emitted <= valid_signals:
+        raise HygieneError(f"{cls.__name__} emits unknown scanner signals: {sorted(emitted - valid_signals)}")
+    try:
+        pd.to_numeric(signals["signal_strength"])
+    except Exception as exc:  # noqa: BLE001
+        raise HygieneError(f"{cls.__name__} signal_strength must be numeric") from exc
+
+
+def _scanner_sample(cls: Type, instance):
+    """OHLCV long enough for a scanner's own warm-up, and eventful enough to move it.
+
+    A fixed five-bar frame was neither, and every scanner needs more than five bars.
+    One that guards on ``required_data_points()`` was rejected for a sample too short
+    to scan; one that does not returned an all-NaN, all-HOLD frame - which passes the
+    signal-vocabulary check trivially, because ``{HOLD}`` is a subset of the
+    vocabulary. So the check could not fail, for any scanner, in either direction.
+
+    The tail carries a volume spike on a decisive up-bar because a scanner that never
+    emits an actionable label is a scanner whose actionable labels went unchecked.
+    """
+    import pandas as pd
+
+    try:
+        required = int(instance.required_data_points())
+    except Exception as exc:  # noqa: BLE001 - a scanner that cannot say is not valid
+        raise HygieneError(f"{cls.__name__} cannot report required_data_points: {exc}") from exc
+    if required < 1:
+        raise HygieneError(f"{cls.__name__} reports required_data_points={required}")
+
+    n = max(required + 5, 30)
+    opens = [100.0 + i * 0.25 for i in range(n)]
+    closes = [price + 0.1 for price in opens]
+    volumes = [300_000.0] * n
+    # The event: a decisive up-bar on heavy volume, so thresholds on ratio, move and
+    # liquidity are all cleared at once and an actionable label is actually reachable.
+    opens[-1], closes[-1] = 100.0, 103.0
+    volumes[-1] = 2_000_000.0
+    return pd.DataFrame(
+        {
+            "open": opens,
+            "high": [max(o, c) + 1.0 for o, c in zip(opens, closes)],
+            "low": [min(o, c) - 1.0 for o, c in zip(opens, closes)],
+            "close": closes,
+            "volume": volumes,
+        },
+        index=pd.date_range("2024-01-02", periods=n, freq="D"),
+    )
+
+
+def _guarded_import(name, *args, **kwargs):
+    root = name.split(".")[0]
+    if root == "tradeflow":
+        # Older prompts and drafts name the package this one replaced; say where the
+        # module went instead of reporting a permission problem that does not exist.
+        raise HygieneError(
+            f"generated code may not import {name!r}: the package is now `quantred`, "
+            f"so import from `quantred` ({name.replace('tradeflow', 'quantred', 1)!r})"
+        )
+    if name in _ALLOWED_IMPORTS or root in {"pandas", "numpy", "math"} or name.startswith("quantred."):
+        if name.startswith("quantred.") and name not in _ALLOWED_IMPORTS and root == "quantred":
+            # Only allow the explicitly whitelisted quantred.* modules.
+            if not any(name == allowed or name.startswith(allowed + ".") for allowed in _ALLOWED_IMPORTS):
+                raise HygieneError(f"generated code may not import {name!r}")
+        return _builtins.__import__(name, *args, **kwargs)
+    raise HygieneError(f"generated code may not import {name!r}")
+
+
+def _restricted_builtins() -> dict:
+    allowed = {k: getattr(_builtins, k) for k in dir(_builtins) if k not in _DENIED_BUILTINS}
+    allowed["__import__"] = _guarded_import
+    return allowed

quantred/risk/__init__.py

@@ -0,0 +1,60 @@
+"""Risk model: the covariance matrix Σ and the quantities built on it.
+
+Active management needs a structural answer to "how risky is this portfolio?" that
+respects the fact that risk is not additive. This module estimates an annualized,
+well-conditioned, invertible Σ over a universe (Ledoit–Wolf shrinkage in v1) and
+exposes portfolio variance, tracking error, and marginal contribution to risk.
+Research-clock only: Σ sizes conviction, it never reaches the order path.
+"""
+
+from quantred.risk.base import RiskMatrix, RiskModel, build_return_panel, build_risk_matrix
+from quantred.risk.conditional import (
+    condition_risk_matrix,
+    default_lambda,
+    evaluate_vol_forecasts,
+    mincer_zarnowitz,
+    qlike_loss,
+    turnover_risk_share,
+)
+from quantred.risk.exposures import FACTOR_NAMES, build_factor_exposures
+from quantred.risk.factor import FactorRiskMatrix, build_factor_risk_matrix, estimate_factor_model
+from quantred.risk.sample import LedoitWolfCovariance, SampleCovariance
+from quantred.risk.streaming import streaming_factor_risk_matrix, streaming_sample_covariance
+
+#: Conditional-vol backends accepted by ``build_risk_matrix``/``build_factor_risk_matrix``.
+CONDITIONAL_VOL_MODELS = ("ewma", "har")
+
+#: Statistical estimators by name (the `RiskModel.estimate` interface).
+RISK_MODELS = {
+    "shrinkage": LedoitWolfCovariance,
+    "sample": SampleCovariance,
+}
+
+#: Every covariance model name the surfaces accept ("factor" is structural, built
+#: from exposures rather than a plain estimator).
+COVARIANCE_MODELS = (*RISK_MODELS, "factor")
+
+__all__ = [
+    "RiskMatrix",
+    "RiskModel",
+    "build_return_panel",
+    "build_risk_matrix",
+    "LedoitWolfCovariance",
+    "SampleCovariance",
+    "RISK_MODELS",
+    "COVARIANCE_MODELS",
+    "FACTOR_NAMES",
+    "build_factor_exposures",
+    "FactorRiskMatrix",
+    "estimate_factor_model",
+    "build_factor_risk_matrix",
+    "streaming_sample_covariance",
+    "streaming_factor_risk_matrix",
+    "condition_risk_matrix",
+    "default_lambda",
+    "evaluate_vol_forecasts",
+    "mincer_zarnowitz",
+    "qlike_loss",
+    "turnover_risk_share",
+    "CONDITIONAL_VOL_MODELS",
+]

quantred/risk/base.py

@@ -0,0 +1,218 @@
+"""Risk model core - the covariance matrix Σ and the quantities built on it.
+
+A portfolio's risk is **not** additive: two names that move together are one bet,
+two that move oppositely are a hedge. The covariance matrix Σ is what lets the
+optimizer (and the diagnostics) tell the difference - compute portfolio variance,
+tracking error, and each name's marginal contribution to risk.
+
+This module owns the shared types: :class:`RiskMatrix` (an annualized Σ plus the
+derived quantities) and :class:`RiskModel` (the estimator interface). Concrete
+estimators live in :mod:`quantred.risk.sample`. Everything is research-clock: Σ is a tool
+for sizing conviction, never consulted to place an order.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Dict, List, Mapping, Optional, Tuple, Union
+
+import numpy as np
+import pandas as pd
+
+Weights = Union[Mapping[str, float], np.ndarray]
+
+
+@dataclass
+class RiskMatrix:
+    """An annualized covariance matrix Σ over a universe, plus risk math on it."""
+
+    symbols: List[str]
+    sigma: np.ndarray  # N×N annualized covariance, positive-definite
+    shrinkage: Optional[float] = None  # δ used (Ledoit–Wolf), for audit
+    #: Set when Σ was conditioned: method, λ, per-name D_t vs the
+    #: unconditional diagonal (the "sigma_regime" diagnostic). ``None`` unconditional.
+    conditional_diagnostics: Optional[Dict[str, Any]] = None
+
+    def __post_init__(self) -> None:
+        self._index = {sym: i for i, sym in enumerate(self.symbols)}
+
+    # ------------------------------------------------------------------ #
+    # Weight handling
+    # ------------------------------------------------------------------ #
+    def _vector(self, weights: Weights) -> np.ndarray:
+        """Align a weight mapping to Σ's symbol order (missing names → 0)."""
+        if isinstance(weights, np.ndarray):
+            if weights.shape != (len(self.symbols),):
+                raise ValueError(f"weight vector must have length {len(self.symbols)}")
+            return weights.astype(float)
+        vec = np.zeros(len(self.symbols))
+        for sym, w in weights.items():
+            idx = self._index.get(sym)
+            if idx is not None:
+                vec[idx] = w
+        return vec
+
+    # ------------------------------------------------------------------ #
+    # Risk quantities (Σ is annualized, so these are annualized too)
+    # ------------------------------------------------------------------ #
+    def variance(self, weights: Weights) -> float:
+        """Portfolio variance ``wᵀ Σ w``."""
+        w = self._vector(weights)
+        return float(w @ self.sigma @ w)
+
+    def volatility(self, weights: Weights) -> float:
+        """Portfolio volatility ``√(wᵀ Σ w)`` (annualized)."""
+        return float(np.sqrt(max(self.variance(weights), 0.0)))
+
+    def tracking_error(self, weights: Weights, benchmark: Weights) -> float:
+        """Tracking error ``√(w_aᵀ Σ w_a)`` for active weights ``w_a = w − w_B``."""
+        active = self._vector(weights) - self._vector(benchmark)
+        return float(np.sqrt(max(active @ self.sigma @ active, 0.0)))
+
+    def implied_beta(self, benchmark: Weights) -> pd.Series:
+        """The Σ-implied benchmark beta per name: ``β = Σw_B / (w_Bᵀ Σ w_B)``.
+
+        The one canonical beta for anything benchmark-portfolio-relative (reverse
+        optimization, active-beta diagnostics, alpha neutralization) - this is
+        "one β, everywhere": per-name regression betas (the alpha
+        pipeline's ``beta`` feature) are a different, complementary quantity and
+        must not be mixed with this one. Zero vector when the benchmark carries no
+        risk (``w_B = 0`` or degenerate Σ), so callers reduce to "no benchmark"
+        rather than dividing by zero.
+        """
+        wb = self._vector(benchmark)
+        denom = float(wb @ self.sigma @ wb)
+        if denom <= 0:
+            return pd.Series(0.0, index=self.symbols)
+        return pd.Series((self.sigma @ wb) / denom, index=self.symbols)
+
+    def marginal_contribution_to_risk(
+        self, weights: Weights, benchmark: Optional[Weights] = None
+    ) -> pd.Series:
+        """Per-name MCR ``(Σ w_a) / ψ`` - ``∂ψ/∂w_a``, the risk gradient."""
+        active = self._vector(weights)
+        if benchmark is not None:
+            active = active - self._vector(benchmark)
+        te = float(np.sqrt(max(active @ self.sigma @ active, 0.0)))
+        if te == 0:
+            return pd.Series(0.0, index=self.symbols)
+        return pd.Series((self.sigma @ active) / te, index=self.symbols)
+
+    def correlation(self) -> pd.DataFrame:
+        """The implied correlation matrix (Σ scaled by its diagonal std)."""
+        std = np.sqrt(np.diag(self.sigma))
+        denom = np.outer(std, std)
+        with np.errstate(divide="ignore", invalid="ignore"):
+            corr = np.where(denom > 0, self.sigma / denom, 0.0)
+        return pd.DataFrame(corr, index=self.symbols, columns=self.symbols)
+
+    def volatilities(self) -> pd.Series:
+        """Annualized volatility per name (√diagonal of Σ)."""
+        return pd.Series(np.sqrt(np.diag(self.sigma)), index=self.symbols)
+
+    def condition_number(self) -> float:
+        """Condition number of Σ - how close to singular (the invertibility guard)."""
+        return float(np.linalg.cond(self.sigma))
+
+    def is_positive_definite(self) -> bool:
+        """Whether Σ is positive-definite (so ``Σ⁻¹`` exists for the optimizer)."""
+        try:
+            np.linalg.cholesky(self.sigma)
+            return True
+        except np.linalg.LinAlgError:
+            return False
+
+
+class RiskModel(ABC):
+    """Estimates a per-bar covariance over a returns panel (columns = symbols)."""
+
+    @abstractmethod
+    def estimate(self, returns: pd.DataFrame) -> Tuple[np.ndarray, Optional[float]]:
+        """Return ``(Σ_per_bar, shrinkage)`` over complete-case ``returns`` columns."""
+
+
+def build_return_panel(bars: Dict[str, pd.DataFrame], min_obs: int = 60) -> Tuple[pd.DataFrame, List[str]]:
+    """Build an aligned (dates × symbols) return panel and the under-sampled names.
+
+    Names enter and leave the universe, so the raw panel is ragged. We keep names
+    with at least ``min_obs`` returns and align them on their common (complete-case)
+    dates; names below the floor are returned separately so the caller can apply the
+    documented fallback (a cross-sectional median variance) rather than drop them.
+    """
+    returns = pd.DataFrame(
+        {sym: frame["close"].pct_change() for sym, frame in bars.items() if not frame.empty}
+    )
+    if returns.empty:
+        return returns, []
+    counts = returns.notna().sum()
+    kept = [sym for sym in returns.columns if counts[sym] >= min_obs]
+    under_sampled = [sym for sym in returns.columns if sym not in kept]
+    panel = returns[kept].dropna() if kept else returns.iloc[0:0]
+    return panel, under_sampled
+
+
+def build_risk_matrix(
+    model: RiskModel,
+    bars: Dict[str, pd.DataFrame],
+    periods_per_year: float,
+    min_obs: int = 60,
+    conditional: Optional[str] = None,
+    conditional_lambda: Optional[float] = None,
+    conditional_horizon: int = 1,
+) -> Optional[RiskMatrix]:
+    """Estimate an annualized :class:`RiskMatrix` over a universe's scanned bars.
+
+    Builds the aligned return panel, estimates Σ on the well-sampled names, annualizes
+    it, and splices in under-sampled names with the documented fallback - a
+    cross-sectional **median variance** and zero correlation - so the matrix spans the
+    full universe and stays positive-definite rather than dropping names silently.
+    Returns ``None`` if no name has enough history.
+
+    ``conditional`` (default ``None`` / off) conditions the well-sampled
+    block's diagonal via an EWMA (``"ewma"``) or HAR-lite (``"har"``) per-name
+    volatility forecast, keeping the correlation structure fixed
+    (``Σ_t = D_t·R·D_t`` - see :mod:`quantred.risk.conditional`), *before* the
+    under-sampled splice below - so thin-history names keep the same
+    unconditional-fallback treatment regardless of conditioning.
+    """
+    panel, under_sampled = build_return_panel(bars, min_obs=min_obs)
+    universe = [sym for sym in bars if not bars[sym].empty]
+    if panel.empty or panel.shape[0] < 2:
+        return None
+
+    sigma_bar, shrinkage = model.estimate(panel)
+    sigma = sigma_bar * periods_per_year
+    kept = list(panel.columns)
+    matrix = RiskMatrix(symbols=kept, sigma=sigma, shrinkage=shrinkage)
+    if conditional:
+        from quantred.risk.conditional import condition_risk_matrix
+
+        matrix = condition_risk_matrix(
+            matrix,
+            panel,
+            conditional,
+            periods_per_year,
+            min_obs=min_obs,
+            lambda_=conditional_lambda,
+            horizon=conditional_horizon,
+        )
+
+    if not under_sampled:
+        return matrix
+
+    # Fallback for thin-history names: independent, at the median estimated variance.
+    median_var = float(np.median(np.diag(matrix.sigma))) if matrix.sigma.size else 0.0
+    order = [sym for sym in universe if sym in kept or sym in under_sampled]
+    idx = {sym: i for i, sym in enumerate(kept)}
+    full = np.zeros((len(order), len(order)))
+    for a, sa in enumerate(order):
+        for b, sb in enumerate(order):
+            if sa in idx and sb in idx:
+                full[a, b] = matrix.sigma[idx[sa], idx[sb]]
+        if sa in under_sampled:
+            full[a, a] = median_var
+    return RiskMatrix(
+        symbols=order,
+        sigma=full,
+        shrinkage=matrix.shrinkage,
+        conditional_diagnostics=matrix.conditional_diagnostics,
+    )