mlquantx 0.2.5__py3-none-any.whl

mlquant/models/losses.py

@@ -0,0 +1,88 @@
+"""Sign-aware regression losses + IC / RankIC objectives.
+
+Why not plain MSE?
+    Trading P&L is sign-sensitive: a prediction with the wrong sign
+    *and* moderate magnitude burns money, while a prediction with the
+    right sign and any magnitude makes money. Plain MSE penalises both
+    "right sign, big residual" and "wrong sign, small residual" the
+    same way — that is well-documented to misalign with utility.
+
+We expose:
+
+* :class:`AdjMSELoss`  — Du (2025) §4.2: scale up the loss when
+  ``sign(pred)·sign(label) < 0``, scale it down when they agree.
+* :class:`ICLoss`      — minus Pearson correlation across the batch.
+* :class:`RankICLoss`  — minus Spearman correlation across the batch.
+
+ICLoss / RankICLoss are particularly useful for *cross-sectional*
+training where what matters is the ordering of predictions within a
+date, not their absolute magnitude.
+"""
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+
+
+class AdjMSELoss(nn.Module):
+    r"""Sign-aware MSE.
+
+    .. math::
+        \mathcal{L}_{\text{adj}}(\hat y, y) =
+        \begin{cases}
+            \gamma\,(\hat y - y)^2 & \text{if }\operatorname{sign}(\hat y)\cdot\operatorname{sign}(y) > 0 \\
+            (1+\gamma)\,(\hat y - y)^2 & \text{otherwise}
+        \end{cases}
+
+    With ``gamma = 0.1`` (default) wrong-sign predictions are penalised
+    11× more than right-sign predictions of equal magnitude.
+    """
+
+    def __init__(self, gamma: float = 0.1) -> None:
+        super().__init__()
+        if gamma <= 0:
+            raise ValueError("gamma must be positive")
+        self.gamma = gamma
+
+    def forward(self, pred: torch.Tensor, target: torch.Tensor) -> torch.Tensor:
+        squared = (pred - target) ** 2
+        same_sign = (pred * target) > 0
+        weight = torch.where(same_sign,
+                             torch.full_like(squared, self.gamma),
+                             torch.full_like(squared, 1.0 + self.gamma))
+        return (squared * weight).mean()
+
+
+def _pearson(x: torch.Tensor, y: torch.Tensor) -> torch.Tensor:
+    xm = x - x.mean()
+    ym = y - y.mean()
+    denom = (xm.pow(2).sum().sqrt() * ym.pow(2).sum().sqrt()).clamp_min(1e-12)
+    return (xm * ym).sum() / denom
+
+
+class ICLoss(nn.Module):
+    """Negative Pearson IC across a batch (e.g. one cross-section)."""
+
+    def forward(self, pred: torch.Tensor, target: torch.Tensor) -> torch.Tensor:
+        return -_pearson(pred, target)
+
+
+class RankICLoss(nn.Module):
+    """Negative Spearman IC across a batch.
+
+    Spearman = Pearson on ranks. We use the *soft-rank* trick (a
+    differentiable approximation that sorts the inputs through a
+    softmax-temperature lens) so the loss is gradient-friendly.
+    """
+
+    def __init__(self, temperature: float = 1.0) -> None:
+        super().__init__()
+        self.temperature = temperature
+
+    def forward(self, pred: torch.Tensor, target: torch.Tensor) -> torch.Tensor:
+        return -_pearson(self._soft_rank(pred), self._soft_rank(target))
+
+    def _soft_rank(self, x: torch.Tensor) -> torch.Tensor:
+        # Differentiable rank: softmax over pairwise differences.
+        diffs = (x.unsqueeze(0) - x.unsqueeze(1)) / self.temperature
+        return torch.sigmoid(diffs).sum(dim=0)

mlquant/models/nets.py

@@ -0,0 +1,62 @@
+"""Two compact baselines: an MLP and a thin Transformer encoder.
+
+Both consume a 1-D feature vector per stock-day and produce a scalar
+prediction. They are intentionally small — the paper argues that the
+*factor engineering* and *portfolio construction* layers carry most of
+the alpha; the model's job is non-linear feature combination, not
+deep representation learning.
+"""
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+
+
+class MLPRegressor(nn.Module):
+    """Three-layer MLP with GELU and dropout."""
+
+    def __init__(self, in_dim: int, hidden: int = 128, dropout: float = 0.1) -> None:
+        super().__init__()
+        self.net = nn.Sequential(
+            nn.Linear(in_dim, hidden),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(hidden, hidden),
+            nn.GELU(),
+            nn.Dropout(dropout),
+            nn.Linear(hidden, 1),
+        )
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.net(x).squeeze(-1)
+
+
+class TransformerRegressor(nn.Module):
+    """Apply a transformer encoder across the *factor* axis.
+
+    We tokenise each factor as one position, project to ``d_model``,
+    add a learned positional embedding, and reduce with a CLS token.
+    For ~50-200 factors this is cheap and lets the network learn
+    pairwise factor interactions without manual cross terms.
+    """
+
+    def __init__(self, in_dim: int, d_model: int = 64, n_heads: int = 4,
+                 depth: int = 2, dropout: float = 0.1) -> None:
+        super().__init__()
+        self.proj = nn.Linear(1, d_model)
+        self.pos  = nn.Parameter(torch.randn(in_dim, d_model) * 0.02)
+        self.cls  = nn.Parameter(torch.randn(1, d_model) * 0.02)
+        layer = nn.TransformerEncoderLayer(
+            d_model=d_model, nhead=n_heads, dim_feedforward=4 * d_model,
+            dropout=dropout, batch_first=True, activation="gelu",
+        )
+        self.encoder = nn.TransformerEncoder(layer, num_layers=depth)
+        self.head = nn.Linear(d_model, 1)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        # x: [B, F] -> tokens [B, F, d_model]
+        tokens = self.proj(x.unsqueeze(-1)) + self.pos
+        cls = self.cls.expand(x.shape[0], -1, -1)
+        seq = torch.cat([cls, tokens], dim=1)
+        h = self.encoder(seq)
+        return self.head(h[:, 0]).squeeze(-1)

mlquant/portfolio/__init__.py

@@ -0,0 +1,5 @@
+"""Cross-sectional Markowitz with α-sweep + shrunk covariance."""
+from .markowitz import MarkowitzOptimizer, MarkowitzConfig
+from .frontier import efficient_frontier
+
+__all__ = ["MarkowitzOptimizer", "MarkowitzConfig", "efficient_frontier"]

mlquant/portfolio/frontier.py

@@ -0,0 +1,49 @@
+"""Sweep the efficient frontier over a grid of risk-aversion values.
+
+The paper sweeps ``α ∈ {0, 0.25, 0.5, 0.75, 1, 2, …, 300}`` to trace the
+efficient frontier; at backtest time you pick a single α (typically the
+one whose ex-ante volatility matches a target). This module runs the
+sweep and returns one row per α with realised return + ex-ante variance.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Sequence
+
+import numpy as np
+
+from .markowitz import MarkowitzConfig, MarkowitzOptimizer
+
+
+@dataclass
+class FrontierPoint:
+    risk_aversion: float
+    expected_return: float
+    expected_variance: float
+    weights: np.ndarray
+
+
+def efficient_frontier(
+    mu: np.ndarray,
+    returns_history: np.ndarray,
+    *,
+    risk_aversions: Sequence[float] = (0.25, 0.5, 1.0, 2.0, 5.0, 10.0, 25.0, 50.0, 100.0),
+    cfg: MarkowitzConfig | None = None,
+) -> list[FrontierPoint]:
+    """Compute one :class:`FrontierPoint` per ``risk_aversion``.
+
+    The optimiser warm-starts between consecutive ``α`` values, so this
+    is significantly cheaper than building a fresh problem for each
+    point.
+    """
+    cfg = cfg or MarkowitzConfig()
+    points: list[FrontierPoint] = []
+    for ra in risk_aversions:
+        local = MarkowitzConfig(**{**cfg.__dict__, "risk_aversion": ra})
+        opt = MarkowitzOptimizer(local)
+        w = opt.solve(mu, returns_history)
+        sigma = opt._covariance(returns_history)                       # noqa: SLF001
+        ev = float(w @ sigma @ w)
+        er = float(mu @ w)
+        points.append(FrontierPoint(ra, er, ev, w))
+    return points

mlquant/portfolio/markowitz.py

@@ -0,0 +1,144 @@
+"""Cross-sectional Markowitz mean-variance optimisation.
+
+Problem
+-------
+For a given prediction vector :math:`\\mu \\in \\mathbb{R}^n` and a
+covariance matrix :math:`\\Sigma`, find weights :math:`w \\in
+\\mathbb{R}^n` solving
+
+.. math::
+
+    \\max_w \\; \\mu^\\top w - \\alpha \\, w^\\top \\Sigma w
+    \\quad
+    \\text{s.t.} \\;
+    \\mathbf{1}^\\top w = 1, \\;
+    0 \\le w \\le w_{\\max}.
+
+We solve this via :mod:`cvxpy` so the default install needs **no
+commercial solver**: ECOS or SCS handle 1 000-asset problems in
+milliseconds. The MOSEK path remains available for users with a
+licence by selecting ``solver="MOSEK"``.
+
+Covariance estimation uses Ledoit–Wolf shrinkage by default, which is
+both faster and more numerically stable than a sample covariance on
+short look-back windows.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import cvxpy as cp
+import numpy as np
+from sklearn.covariance import LedoitWolf
+
+
+@dataclass
+class MarkowitzConfig:
+    risk_aversion: float = 1.0
+    weight_cap:    float = 0.05         # max single-name weight (5 %)
+    long_only:     bool  = True
+    cash_weight:   float = 0.0          # leave x % in cash
+    solver:        str   = "SCS"        # "SCS" / "ECOS" / "MOSEK"
+    shrinkage:     bool  = True
+
+
+class MarkowitzOptimizer:
+    """Stateful optimiser; build once, call :meth:`solve` per date.
+
+    Parameters
+    ----------
+    cfg : MarkowitzConfig
+
+    Notes
+    -----
+    The first call constructs the cvxpy problem. Subsequent calls reuse
+    the parameter objects so ``cvxpy`` skips canonicalisation — this
+    matters when you backtest 3 000 trading days.
+    """
+
+    def __init__(self, cfg: Optional[MarkowitzConfig] = None) -> None:
+        self.cfg = cfg or MarkowitzConfig()
+        self._n: int | None = None
+        self._mu_param: cp.Parameter | None = None
+        self._sigma_param: cp.Parameter | None = None
+        self._w_var: cp.Variable | None = None
+        self._problem: cp.Problem | None = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+    def solve(self, mu: np.ndarray, returns_history: np.ndarray) -> np.ndarray:
+        """Compute portfolio weights for one date.
+
+        Parameters
+        ----------
+        mu : np.ndarray [n]
+            Predicted next-period returns (alpha signal).
+        returns_history : np.ndarray [T, n]
+            Historical returns used to estimate covariance.
+
+        Returns
+        -------
+        w : np.ndarray [n]
+            Long-only (or long-short) weights summing to ``1 - cash_weight``.
+        """
+        n = mu.shape[0]
+        if returns_history.shape[1] != n:
+            raise ValueError("mu and returns_history have mismatched stock dimensions")
+
+        sigma = self._covariance(returns_history)
+        self._build(n)
+        self._mu_param.value = mu.astype(np.float64)
+        self._sigma_param.value = self._psd_project(sigma)
+
+        try:
+            self._problem.solve(solver=self.cfg.solver, warm_start=True)
+        except cp.error.SolverError:
+            # Fall back to SCS if the requested solver is unavailable.
+            self._problem.solve(solver="SCS", warm_start=True)
+
+        w = np.asarray(self._w_var.value).flatten()
+        # Numerical fix-ups
+        w[np.abs(w) < 1e-7] = 0.0
+        if self.cfg.long_only:
+            w = np.clip(w, 0.0, self.cfg.weight_cap)
+        # Renormalise to compensate for clipping rounding.
+        s = w.sum()
+        if s > 0:
+            w *= (1.0 - self.cfg.cash_weight) / s
+        return w
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+    def _covariance(self, history: np.ndarray) -> np.ndarray:
+        if not self.cfg.shrinkage:
+            return np.cov(history, rowvar=False)
+        # LedoitWolf is dramatically more stable on short windows.
+        return LedoitWolf().fit(history).covariance_
+
+    @staticmethod
+    def _psd_project(sigma: np.ndarray) -> np.ndarray:
+        # Symmetric, then nudge eigenvalues to be ≥ 0 to keep cvxpy happy.
+        sigma = 0.5 * (sigma + sigma.T)
+        w, V = np.linalg.eigh(sigma)
+        w = np.clip(w, 1e-10, None)
+        return (V * w) @ V.T
+
+    def _build(self, n: int) -> None:
+        if self._n == n:
+            return
+        self._n = n
+        self._mu_param    = cp.Parameter(n)
+        self._sigma_param = cp.Parameter((n, n), PSD=True)
+        w = cp.Variable(n)
+        objective = cp.Maximize(self._mu_param @ w
+                                - self.cfg.risk_aversion * cp.quad_form(w, self._sigma_param))
+        constraints = [cp.sum(w) == 1.0 - self.cfg.cash_weight]
+        if self.cfg.long_only:
+            constraints += [w >= 0, w <= self.cfg.weight_cap]
+        else:
+            constraints += [w >= -self.cfg.weight_cap, w <= self.cfg.weight_cap]
+        self._w_var = w
+        self._problem = cp.Problem(objective, constraints)

mlquant/training/__init__.py

@@ -0,0 +1,6 @@
+"""Datasets, GBM augmentation, and the training loop."""
+from .dataset import FactorDataset
+from .augment import gbm_augment
+from .trainer import Trainer, TrainConfig
+
+__all__ = ["FactorDataset", "gbm_augment", "Trainer", "TrainConfig"]

mlquant/training/augment.py

@@ -0,0 +1,89 @@
+"""Geometric Brownian Motion data augmentation.
+
+The paper argues that financial time-series datasets are
+*data-poor for the regime that matters*: A-share crashes and rallies
+are rare, and an ML model trained directly on the historical record
+will overfit the most-recent regime. Augmenting the training set with
+GBM-resampled trajectories that share the historical drift and
+volatility — but reshuffle the random shocks — provides extra effective
+sample size without leaking information about the actual future.
+
+This module is intentionally a single, well-tested function; if you
+want path-dependent augmentation (e.g. SDE bridge, bootstrap blocks)
+add a sibling function rather than overloading :func:`gbm_augment`.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Tuple
+
+import torch
+
+
+@dataclass
+class GBMAugmentConfig:
+    n_synthetic: int = 1               # paths produced per real path
+    block_size:  int = 21              # ~1 month, lengths of resampled blocks
+    seed:        int = 0
+
+
+def gbm_augment(
+    log_returns: torch.Tensor,
+    mask: torch.Tensor,
+    cfg: GBMAugmentConfig | None = None,
+) -> Tuple[torch.Tensor, torch.Tensor]:
+    """Block-bootstrap GBM augmentation for log-return panels.
+
+    For each stock we estimate ``μ̂, σ̂`` on the supplied history and
+    resample a synthetic trajectory of identical length:
+
+        r̃_t = μ̂ + σ̂ * ε_t,    ε_t ~ N(0, 1) drawn in blocks of
+                                ``block_size`` so autocorrelation
+                                structure is partly preserved.
+
+    The resulting tensor has shape ``[n_synthetic*T, N]`` and is meant
+    to be *concatenated* with real data at training time (with a
+    binary "is_synthetic" flag exposed by :class:`FactorDataset`).
+
+    Parameters
+    ----------
+    log_returns : Tensor [T, N]   per-stock log returns.
+    mask        : Tensor [T, N]   tradability mask; masked cells do not
+                                  contribute to the μ̂, σ̂ estimate.
+    cfg         : GBMAugmentConfig
+
+    Returns
+    -------
+    aug_log_returns : Tensor [n_synthetic*T, N]
+    aug_mask        : Tensor [n_synthetic*T, N]   ones (synthetic data is
+                                                  always tradable)
+    """
+    cfg = cfg or GBMAugmentConfig()
+    if log_returns.dim() != 2:
+        raise ValueError("log_returns must be [T, N]")
+
+    T, N = log_returns.shape
+    if cfg.block_size <= 0 or cfg.block_size > T:
+        raise ValueError(f"block_size must be in (0, T={T}], got {cfg.block_size}")
+
+    gen = torch.Generator(device=log_returns.device).manual_seed(cfg.seed)
+
+    # Per-stock μ, σ from the masked history.
+    m = mask.float()
+    counts = m.sum(dim=0).clamp_min(2)
+    mu  = (log_returns * m).sum(dim=0) / counts                          # [N]
+    var = (((log_returns - mu) * m) ** 2).sum(dim=0) / (counts - 1)
+    sigma = var.clamp_min(1e-12).sqrt()                                  # [N]
+
+    out_T = cfg.n_synthetic * T
+    out = torch.empty((out_T, N), dtype=log_returns.dtype, device=log_returns.device)
+
+    # Block-bootstrap eps: draw block-aligned standardised innovations.
+    n_blocks = (out_T + cfg.block_size - 1) // cfg.block_size
+    eps = torch.randn((n_blocks * cfg.block_size, N), generator=gen,
+                      dtype=log_returns.dtype, device=log_returns.device)
+    eps = eps[:out_T]
+
+    out[:] = mu.unsqueeze(0) + sigma.unsqueeze(0) * eps
+    aug_mask = torch.ones_like(out, dtype=torch.bool)
+    return out, aug_mask

mlquant/training/dataset.py

@@ -0,0 +1,50 @@
+"""Cross-sectional dataset for daily-rebalance models.
+
+Each sample is *one stock-day* — features at date ``t``, label is the
+next-day return at ``t+1``. The dataset takes care of:
+
+* aligning the factor tensor with the bias-corrected mask,
+* shifting the label by one day,
+* dropping cells where either side of the prediction is non-tradable,
+* exposing batches as plain ``(features, labels)`` pairs.
+"""
+from __future__ import annotations
+
+from typing import Optional, Tuple
+
+import torch
+from torch.utils.data import Dataset
+
+
+class FactorDataset(Dataset):
+    """A flat dataset of (factor vector, next-day return) pairs."""
+
+    def __init__(
+        self,
+        factors: torch.Tensor,            # [T, N, F]
+        mask:    torch.Tensor,            # [T, N]
+        forward_returns: torch.Tensor,    # [T, N]   already bias-corrected
+        *,
+        date_index: Optional[torch.Tensor] = None,
+        stock_index: Optional[torch.Tensor] = None,
+    ) -> None:
+        if factors.dim() != 3:
+            raise ValueError("factors must be [T, N, F]")
+        T, N, _ = factors.shape
+
+        # Drop the last day (no forward return available) and any masked
+        # cells.
+        valid = mask[:-1] & mask[1:] & ~torch.isnan(forward_returns[:-1])
+        flat_idx = valid.nonzero(as_tuple=False)        # [K, 2] (t, n)
+
+        self.features = factors[:-1][flat_idx[:, 0], flat_idx[:, 1]]
+        self.labels   = forward_returns[:-1][flat_idx[:, 0], flat_idx[:, 1]]
+
+        self.dates  = (date_index[:-1] [flat_idx[:, 0]] if date_index  is not None else flat_idx[:, 0])
+        self.stocks = (stock_index    [flat_idx[:, 1]] if stock_index is not None else flat_idx[:, 1])
+
+    def __len__(self) -> int:
+        return self.features.shape[0]
+
+    def __getitem__(self, idx: int) -> Tuple[torch.Tensor, torch.Tensor]:
+        return self.features[idx], self.labels[idx]

mlquant/training/trainer.py

@@ -0,0 +1,108 @@
+"""A small, self-contained training loop.
+
+This is *not* a competitor to PyTorch Lightning — it's the minimum
+needed to get a model trained, validated, and checkpointed against a
+:class:`FactorDataset`. Everything is explicit so the training-time
+behaviour matches what's documented in the paper.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Callable, Iterable, Optional
+
+import torch
+import torch.nn as nn
+from torch.utils.data import DataLoader
+
+from .dataset import FactorDataset
+
+
+@dataclass
+class TrainConfig:
+    epochs:      int   = 30
+    batch_size:  int   = 1024
+    lr:          float = 1e-3
+    weight_decay:float = 1e-5
+    grad_clip:   float = 1.0
+    device:      str   = "cpu"
+    log_every:   int   = 50
+    save_dir:    str   = "checkpoints"
+    val_split:   float = 0.1
+    extra:       dict  = field(default_factory=dict)
+
+
+class Trainer:
+    def __init__(
+        self,
+        model: nn.Module,
+        loss_fn: Callable[[torch.Tensor, torch.Tensor], torch.Tensor],
+        cfg: TrainConfig,
+    ) -> None:
+        self.model = model.to(cfg.device)
+        self.loss_fn = loss_fn
+        self.cfg = cfg
+        self.optim = torch.optim.AdamW(
+            model.parameters(),
+            lr=cfg.lr,
+            weight_decay=cfg.weight_decay,
+        )
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+    def fit(self, dataset: FactorDataset) -> dict:
+        n_val = max(1, int(len(dataset) * self.cfg.val_split))
+        n_train = len(dataset) - n_val
+        train_ds, val_ds = torch.utils.data.random_split(
+            dataset, [n_train, n_val],
+            generator=torch.Generator().manual_seed(0),
+        )
+        train_loader = DataLoader(train_ds, batch_size=self.cfg.batch_size,
+                                  shuffle=True, drop_last=True)
+        val_loader   = DataLoader(val_ds,   batch_size=self.cfg.batch_size)
+
+        history: dict = {"train_loss": [], "val_loss": []}
+        save_dir = Path(self.cfg.save_dir)
+        save_dir.mkdir(parents=True, exist_ok=True)
+        best_val = float("inf")
+
+        for epoch in range(self.cfg.epochs):
+            train_loss = self._run_epoch(train_loader, train=True)
+            val_loss   = self._run_epoch(val_loader,   train=False)
+            history["train_loss"].append(train_loss)
+            history["val_loss"].append(val_loss)
+            print(f"[epoch {epoch:3d}] train={train_loss:.5f}  val={val_loss:.5f}")
+
+            if val_loss < best_val:
+                best_val = val_loss
+                torch.save(self.model.state_dict(), save_dir / "best.pt")
+        torch.save(self.model.state_dict(), save_dir / "last.pt")
+        return history
+
+    @torch.no_grad()
+    def predict(self, features: torch.Tensor) -> torch.Tensor:
+        self.model.eval()
+        return self.model(features.to(self.cfg.device)).detach().cpu()
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+    def _run_epoch(self, loader: Iterable, *, train: bool) -> float:
+        self.model.train(train)
+        total, n = 0.0, 0
+        for x, y in loader:
+            x = x.to(self.cfg.device)
+            y = y.to(self.cfg.device)
+            if train:
+                self.optim.zero_grad(set_to_none=True)
+            preds = self.model(x)
+            loss = self.loss_fn(preds, y)
+            if train:
+                loss.backward()
+                if self.cfg.grad_clip:
+                    nn.utils.clip_grad_norm_(self.model.parameters(), self.cfg.grad_clip)
+                self.optim.step()
+            total += loss.item() * x.shape[0]
+            n     += x.shape[0]
+        return total / max(1, n)

mlquant/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Cross-cutting utilities: config loading, seeding, logging."""
+from .config import Config, load_config
+from .seed import seed_everything
+
+__all__ = ["Config", "load_config", "seed_everything"]

mlquant/utils/config.py

@@ -0,0 +1,60 @@
+"""Tiny YAML-config loader.
+
+Why not Hydra? — Hydra is great but pulls 6 MB of deps for a single
+``yaml.safe_load`` and a few path joins. Forty lines of stdlib do
+exactly what we need without taking a dependency on a config framework.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict
+
+import yaml
+
+
+@dataclass
+class Config:
+    """A nested-dict config with attribute access.
+
+    Example
+    -------
+    >>> c = Config({"data": {"n_stocks": 200}, "seed": 42})
+    >>> c.data.n_stocks
+    200
+    >>> c.seed
+    42
+    """
+
+    _data: Dict[str, Any] = field(default_factory=dict)
+
+    def __getattr__(self, item: str) -> Any:                # noqa: D401
+        if item.startswith("_"):
+            raise AttributeError(item)
+        try:
+            value = self._data[item]
+        except KeyError as exc:                             # pragma: no cover
+            raise AttributeError(item) from exc
+        return Config(value) if isinstance(value, dict) else value
+
+    def __getitem__(self, item: str) -> Any:
+        value = self._data[item]
+        return Config(value) if isinstance(value, dict) else value
+
+    def __contains__(self, item: str) -> bool:
+        return item in self._data
+
+    def get(self, item: str, default: Any = None) -> Any:
+        return self._data.get(item, default)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return dict(self._data)
+
+
+def load_config(path: str | Path) -> Config:
+    """Load a YAML file into a :class:`Config`."""
+    with open(path, "r", encoding="utf-8") as fh:
+        data = yaml.safe_load(fh) or {}
+    if not isinstance(data, dict):
+        raise ValueError(f"Top-level of {path} must be a mapping, got {type(data).__name__}")
+    return Config(data)