allocation 0.0.1__py3-none-any.whl

allocation/base.py

@@ -0,0 +1,141 @@
+"""Base class for online portfolio estimators.
+
+``BaseOnlinePortfolio`` follows scikit-learn / skfolio conventions: hyperparameters
+in ``__init__``, ``fit(X)`` / ``partial_fit(X)`` taking asset returns ``X`` and
+storing weights in ``weights_``, plus a ``predict`` that returns portfolio
+returns. Subclasses implement two hooks:
+
+* ``_cold_start(cov)`` -- compute weights from scratch given a covariance, and
+  initialise any persistent state (e.g. a fixed seed ensemble);
+* ``_online_update(cov)`` -- update weights for a new covariance, reusing that
+  state (this is where the smooth, low-turnover transport happens).
+
+Covariance is produced by a pluggable estimator (default :class:`EwmaCovariance`);
+anything exposing ``partial_fit`` and ``covariance_`` works, including the
+``precise`` skaters.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .moments import EwmaCovariance
+
+__all__ = ["BaseOnlinePortfolio"]
+
+
+class NotFittedError(ValueError):
+    pass
+
+
+class BaseOnlinePortfolio:
+    # subclasses set hyperparameters in their own __init__ then call super().__init__()
+    def __init__(self, covariance_estimator=None, halflife: float = 60.0):
+        self.covariance_estimator = covariance_estimator
+        self.halflife = halflife
+        self._cov_estimator = None
+        self._weights: np.ndarray | None = None
+        self.n_features_in_: int | None = None
+        self._n_updates = 0
+
+    # ------------------------------------------------------------------ hooks
+    def _cold_start(self, cov: np.ndarray) -> None:
+        raise NotImplementedError
+
+    def _online_update(self, cov: np.ndarray) -> None:
+        raise NotImplementedError
+
+    # ------------------------------------------------------------- internals
+    def _new_cov_estimator(self):
+        if self.covariance_estimator is None:
+            return EwmaCovariance(halflife=self.halflife)
+        # a pluggable estimator instance (skfolio.moments, precise skater, ...)
+        est = self.covariance_estimator
+        if hasattr(est, "fit") or hasattr(est, "partial_fit"):
+            return est
+        raise TypeError(
+            "covariance_estimator must be None or expose fit/partial_fit and covariance_"
+        )
+
+    @staticmethod
+    def _as_2d(X) -> np.ndarray:
+        X = np.asarray(X, dtype=float)
+        return X[None, :] if X.ndim == 1 else X
+
+    def _feed(self, X) -> np.ndarray:
+        self._cov_estimator.partial_fit(X)
+        return np.asarray(self._cov_estimator.covariance_, dtype=float)
+
+    # -------------------------------------------------------------- fitting
+    def fit(self, X, y=None):
+        X = self._as_2d(X)
+        self.n_features_in_ = X.shape[1]
+        self._cov_estimator = self._new_cov_estimator()
+        if hasattr(self._cov_estimator, "fit"):
+            self._cov_estimator.fit(X)
+        cov = np.asarray(self._cov_estimator.covariance_, dtype=float)
+        self._cold_start(cov)
+        self._n_updates = 1
+        return self
+
+    def partial_fit(self, X, y=None):
+        if self._weights is None:
+            return self.fit(X)
+        X = self._as_2d(X)
+        if X.shape[1] != self.n_features_in_:
+            raise ValueError(
+                "number of assets changed; keyed dynamic-universe support is not "
+                "wired up yet (see universe.py). Re-fit, or pass a fixed universe."
+            )
+        cov = self._feed(X)
+        self._online_update(cov)
+        self._n_updates += 1
+        return self
+
+    # --------------------------------------------------- fitted attributes
+    @property
+    def weights_(self) -> np.ndarray:
+        if self._weights is None:
+            raise NotFittedError(f"{type(self).__name__} is not fitted; call fit first.")
+        return self._weights
+
+    def predict(self, X) -> np.ndarray:
+        """Portfolio returns of each row of ``X`` under the fitted weights."""
+        return self._as_2d(X) @ self.weights_
+
+    def score(self, X, y=None) -> float:
+        """Per-period Sharpe ratio of the portfolio on ``X`` (higher is better).
+
+        Follows skfolio's convention that an optimizer's score is the Sharpe
+        ratio of its predicted portfolio, so the estimator works with
+        scikit-learn / skfolio model-selection out of the box.
+        """
+        r = np.asarray(self.predict(X), dtype=float)
+        sd = float(np.std(r))
+        return float(np.mean(r) / sd) if sd > 0 else 0.0
+
+    def to_portfolio(self, X):
+        """Wrap the fitted weights as a skfolio ``Portfolio`` (optional dependency).
+
+        Lets the estimator's output drop into skfolio's metrics, ``Population``,
+        and plotting, and is the bridge for contributing the estimator upstream
+        (where ``predict`` returns a ``Portfolio`` natively). Requires skfolio.
+        """
+        try:
+            from skfolio import Portfolio
+        except Exception as exc:  # pragma: no cover - optional dependency
+            raise ImportError(
+                "to_portfolio requires skfolio (pip install skfolio)"
+            ) from exc
+        return Portfolio(X=X, weights=self.weights_)
+
+    def get_params(self, deep: bool = True) -> dict:
+        import inspect
+
+        names = [p for p in inspect.signature(self.__init__).parameters if p != "self"]
+        return {k: getattr(self, k) for k in names}
+
+    def set_params(self, **params):
+        for k, v in params.items():
+            setattr(self, k, v)
+        return self

allocation/keyed.py

@@ -0,0 +1,223 @@
+"""River-style streaming portfolio over a *changing* universe.
+
+Real backtests cannot assume a fixed asset set: index members are added and
+dropped, names list and delist. Following river, the streaming interface is
+dict-based -- ``learn_one(x)`` with ``x = {asset_id: return}`` and
+``predict_one()`` returning ``{asset_id: weight}`` -- so a changing universe is
+handled natively: it is just a changing set of dict keys.
+
+Per-asset state is keyed by id and carried across updates. The common-seed
+transport composes with this: each asset owns a persistent seed column, so a
+continuing name keeps its column (and a smooth weight), a new name gets a fresh
+column, and a dropped name's column simply falls out of the active set.
+"""
+
+from __future__ import annotations
+
+import zlib
+
+import numpy as np
+
+from ._schur.coupling import compute_monotonic_weights, compute_weights
+from ._schur.seriation import seriate
+from ._thurstone.ability import base_density
+from ._thurstone.calibrate import calibrate_diagonal, calibrate_one_factor
+from ._thurstone.covariance import market_betas, one_factor_corr
+from ._thurstone.diagonal import diagonal_portfolio
+from ._thurstone.transport import blend_correlation, transport_weights
+
+__all__ = ["KeyedEwmaCovariance", "StreamingThurstone", "StreamingSchur"]
+
+
+def _halflife_to_alpha(halflife: float) -> float:
+    return 1.0 - 0.5 ** (1.0 / max(float(halflife), 1e-9))
+
+
+class KeyedEwmaCovariance:
+    """Dict-keyed exponentially-weighted online covariance.
+
+    ``learn_one({id: value})`` updates means and pairwise covariances keyed by
+    asset id; ``matrix(ids)`` returns the covariance submatrix for any set of
+    ids. Assets may appear or disappear between calls.
+    """
+
+    def __init__(self, halflife: float = 60.0):
+        self.halflife = halflife
+        self.mean: dict = {}
+        self.cov: dict = {}  # frozenset-like sorted (i, j) -> ewma covariance
+        self.count: dict = {}
+
+    def learn_one(self, x: dict) -> "KeyedEwmaCovariance":
+        a = _halflife_to_alpha(self.halflife)
+        for k, v in x.items():
+            self.mean[k] = v if k not in self.mean else (1 - a) * self.mean[k] + a * v
+            self.count[k] = self.count.get(k, 0) + 1
+        dev = {k: x[k] - self.mean[k] for k in x}
+        keys = list(x.keys())
+        for i in keys:
+            di = dev[i]
+            for j in keys:
+                if j < i:
+                    continue
+                key = (i, j)
+                self.cov[key] = (1 - a) * self.cov.get(key, 0.0) + a * di * dev[j]
+        return self
+
+    def matrix(self, ids) -> np.ndarray:
+        ids = list(ids)
+        n = len(ids)
+        C = np.zeros((n, n), dtype=float)
+        for a, i in enumerate(ids):
+            for b in range(a, n):
+                j = ids[b]
+                key = (i, j) if i <= j else (j, i)
+                val = self.cov.get(key, 0.0)
+                C[a, b] = C[b, a] = val
+        # guard a strictly-positive diagonal for assets seen at least once
+        d = np.diag(C).copy()
+        d[d <= 0] = 1e-8
+        np.fill_diagonal(C, d)
+        return C
+
+
+class StreamingThurstone:
+    """Streaming Thurstone portfolio over a changing universe (river-style).
+
+    Parameters mirror :class:`allocation.ThurstonePortfolio`. The active universe
+    at each step is the set of ids present in the latest observation.
+    """
+
+    def __init__(
+        self,
+        *,
+        calib: str = "diagonal",
+        phi: float = 1.0,
+        n_paths: int = 1 << 12,
+        n_quad: int = 16,
+        halflife: float = 60.0,
+        seed: int = 42,
+        min_obs: int = 20,
+    ):
+        if not 0.0 <= phi <= 1.0:
+            raise ValueError("phi must lie in [0, 1].")
+        self.calib = calib
+        self.phi = phi
+        self.n_paths = 1 << int(np.ceil(np.log2(max(int(n_paths), 2))))
+        self.n_quad = n_quad
+        self.halflife = halflife
+        self.seed = seed
+        self.min_obs = min_obs
+        self._cov = KeyedEwmaCovariance(halflife=halflife)
+        self._seed_bank: dict = {}
+        self._weights: dict = {}
+        self._base = base_density()
+        self._n = 0
+
+    # --------------------------------------------------------- seed bank
+    def _seed_column(self, asset_id) -> np.ndarray:
+        col = self._seed_bank.get(asset_id)
+        if col is None:
+            # stable, per-asset, reproducible across sessions
+            h = zlib.crc32(str(asset_id).encode()) & 0xFFFFFFFF
+            rng = np.random.default_rng((self.seed, h))
+            col = rng.standard_normal(self.n_paths)
+            self._seed_bank[asset_id] = col
+        return col
+
+    def _seeds(self, ids) -> np.ndarray:
+        return np.column_stack([self._seed_column(k) for k in ids])
+
+    # --------------------------------------------------------- streaming
+    def learn_one(self, x: dict) -> "StreamingThurstone":
+        self._cov.learn_one(x)
+        self._n += 1
+        # only allocate to assets that have warmed up (a reliable variance);
+        # this is what keeps a freshly-listed name from hijacking the
+        # inverse-variance target with a cold, near-zero variance estimate.
+        warm = [k for k in sorted(x.keys()) if self._cov.count.get(k, 0) >= self.min_obs]
+        if len(warm) >= 2:
+            self._recompute(warm)
+        return self
+
+    def _recompute(self, ids) -> None:
+        cov = self._cov.matrix(ids)
+        tgt = diagonal_portfolio(cov)
+        if self.calib == "market":
+            betas = market_betas(cov, weights=tgt)
+            C_calib = one_factor_corr(betas)
+            ability = calibrate_one_factor(tgt, betas, base=self._base, n_quad=self.n_quad)
+        else:
+            C_calib = np.eye(len(ids))
+            ability = calibrate_diagonal(tgt, base=self._base)
+        C_tilt = blend_correlation(C_calib, cov, self.phi)
+        w = transport_weights(ability, C_tilt, self._seeds(ids))
+        self._weights = dict(zip(ids, w))
+
+    def predict_one(self, x: dict | None = None) -> dict:
+        """Current portfolio as ``{asset_id: weight}`` (a copy)."""
+        return dict(self._weights)
+
+    @property
+    def weights(self) -> dict:
+        return dict(self._weights)
+
+
+class StreamingSchur:
+    """Streaming Schur-complementary portfolio over a changing universe.
+
+    River-style ``learn_one({asset: ret})`` / ``predict_one()``. The Fiedler
+    seriation is carried as a per-asset dict so its sign (hence the order) stays
+    stable as the universe changes. Parameters mirror
+    :class:`allocation.SchurComplementary`.
+    """
+
+    def __init__(
+        self,
+        *,
+        gamma: float = 0.5,
+        keep_monotonic: bool = True,
+        knn: int | None = None,
+        halflife: float = 60.0,
+        min_obs: int = 20,
+    ):
+        if not 0.0 <= gamma <= 1.0:
+            raise ValueError("gamma must lie in [0, 1].")
+        self.gamma = gamma
+        self.keep_monotonic = keep_monotonic
+        self.knn = knn
+        self.halflife = halflife
+        self.min_obs = min_obs
+        self._cov = KeyedEwmaCovariance(halflife=halflife)
+        self._fiedler: dict = {}  # asset_id -> Fiedler coordinate (for sign stability)
+        self._weights: dict = {}
+        self._n = 0
+
+    def learn_one(self, x: dict) -> "StreamingSchur":
+        self._cov.learn_one(x)
+        self._n += 1
+        warm = [k for k in sorted(x.keys()) if self._cov.count.get(k, 0) >= self.min_obs]
+        if len(warm) >= 2:
+            self._recompute(warm)
+        return self
+
+    def _recompute(self, ids) -> None:
+        cov = self._cov.matrix(ids)
+        prev = (
+            np.array([self._fiedler.get(k, 0.0) for k in ids])
+            if self._fiedler
+            else None
+        )
+        order, v = seriate(cov, previous=prev, knn=self.knn)
+        self._fiedler = dict(zip(ids, v))
+        if self.keep_monotonic:
+            w, _ = compute_monotonic_weights(order, cov, self.gamma)
+        else:
+            w = compute_weights(order, cov, self.gamma)
+        self._weights = dict(zip(ids, w))
+
+    def predict_one(self, x: dict | None = None) -> dict:
+        return dict(self._weights)
+
+    @property
+    def weights(self) -> dict:
+        return dict(self._weights)

allocation/moments.py

@@ -0,0 +1,62 @@
+"""Online covariance for the portfolio estimators.
+
+A light, numpy-only EWMA covariance is the default so the package has no heavy
+dependencies. Any external online estimator that exposes a ``covariance_``
+attribute and a ``partial_fit`` method (e.g. the ``precise`` covariance skaters)
+can be plugged in instead -- the portfolio estimators only ever read
+``covariance_``.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["EwmaCovariance"]
+
+
+def _halflife_to_alpha(halflife: float) -> float:
+    return 1.0 - 0.5 ** (1.0 / max(float(halflife), 1e-9))
+
+
+class EwmaCovariance:
+    """Exponentially-weighted online mean/covariance estimator.
+
+    Mirrors the minimal surface the portfolio estimators rely on:
+    ``partial_fit(X)`` / ``fit(X)`` and the fitted ``covariance_``.
+    """
+
+    def __init__(self, halflife: float = 60.0):
+        self.halflife = halflife
+        self._mean: np.ndarray | None = None
+        self._cov: np.ndarray | None = None
+        self.n_samples_ = 0
+
+    def _rows(self, X) -> np.ndarray:
+        X = np.asarray(X, dtype=float)
+        return X[None, :] if X.ndim == 1 else X
+
+    def partial_fit(self, X, y=None) -> "EwmaCovariance":
+        alpha = _halflife_to_alpha(self.halflife)
+        for x in self._rows(X):
+            if self._mean is None:
+                n = len(x)
+                self._mean = x.copy()
+                self._cov = np.zeros((n, n), dtype=float)
+            else:
+                self._mean = (1 - alpha) * self._mean + alpha * x
+            dev = x - self._mean
+            self._cov = (1 - alpha) * self._cov + alpha * np.outer(dev, dev)
+            self.n_samples_ += 1
+        return self
+
+    def fit(self, X, y=None) -> "EwmaCovariance":
+        self._mean = None
+        self._cov = None
+        self.n_samples_ = 0
+        return self.partial_fit(X)
+
+    @property
+    def covariance_(self) -> np.ndarray:
+        if self._cov is None:
+            raise ValueError("EwmaCovariance has not seen any data yet.")
+        return 0.5 * (self._cov + self._cov.T)

allocation/schur.py

@@ -0,0 +1,101 @@
+"""Schur-complementary portfolio as an online estimator.
+
+Your Schur Complementary allocation (the ``gamma`` cross-block coupling that
+interpolates HRP at ``gamma=0`` and minimum variance as ``gamma->1``), but with
+the asset order coming from **Fiedler seriation** instead of agglomerative
+linkage. Because the Fiedler order is a smooth function of the covariance, the
+whole allocation is smooth -- so ``partial_fit`` over a drifting covariance gives
+low-turnover updates, the same streaming property the Thurstone estimator has.
+
+The seriation sign is carried across updates so the order stays stable; the
+similarity graph can be kNN-sparsified and blended with a prior (sectors /
+fundamentals / LLM) for scale and cold-start placement.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .base import BaseOnlinePortfolio
+from ._schur.coupling import compute_monotonic_weights, compute_weights
+from ._schur.seriation import seriate
+
+__all__ = ["SchurComplementary"]
+
+
+class SchurComplementary(BaseOnlinePortfolio):
+    """Online Schur-complementary portfolio with Fiedler seriation.
+
+    Parameters
+    ----------
+    gamma : float in [0, 1], default 0.5
+        Cross-block coupling. 0 = HRP (block-diagonal); ->1 = minimum variance.
+    knn : int or None, default None
+        If set, sparsify the similarity graph to k nearest neighbours (for scale).
+    prior : array (n, n) or None, default None
+        Optional prior similarity blended into the seriation graph.
+    prior_weight : float in [0, 1], default 0.0
+        Weight on ``prior`` in the similarity blend.
+    covariance_estimator : estimator or None, default None
+        Online covariance (``partial_fit`` / ``covariance_``). None uses EWMA.
+    halflife : float, default 60.0
+        EWMA halflife when ``covariance_estimator is None``.
+    """
+
+    def __init__(
+        self,
+        *,
+        gamma: float = 0.5,
+        keep_monotonic: bool = True,
+        knn: int | None = None,
+        prior=None,
+        prior_weight: float = 0.0,
+        covariance_estimator=None,
+        halflife: float = 60.0,
+    ):
+        super().__init__(covariance_estimator=covariance_estimator, halflife=halflife)
+        self.gamma = gamma
+        self.keep_monotonic = keep_monotonic
+        self.knn = knn
+        self.prior = prior
+        self.prior_weight = prior_weight
+        self._fiedler = None
+        self._order = None
+        self.effective_gamma_ = None
+
+    def _seriate(self, cov: np.ndarray):
+        order, v = seriate(
+            cov,
+            previous=self._fiedler,
+            knn=self.knn,
+            prior=self.prior,
+            prior_weight=self.prior_weight,
+        )
+        self._fiedler = v
+        self._order = order
+        return order
+
+    def _allocate(self, order, cov) -> None:
+        if self.keep_monotonic:
+            self._weights, self.effective_gamma_ = compute_monotonic_weights(
+                order, cov, self.gamma
+            )
+        else:
+            self._weights = compute_weights(order, cov, self.gamma)
+            self.effective_gamma_ = self.gamma
+
+    def _cold_start(self, cov: np.ndarray) -> None:
+        if not 0.0 <= self.gamma <= 1.0:
+            raise ValueError("gamma must lie in [0, 1].")
+        self._allocate(self._seriate(cov), cov)
+
+    def _online_update(self, cov: np.ndarray) -> None:
+        self._allocate(self._seriate(cov), cov)  # warm-started sign keeps order stable
+
+    @property
+    def order_(self) -> np.ndarray:
+        return self._order
+
+    @property
+    def fiedler_(self) -> np.ndarray:
+        return self._fiedler

allocation/thurstone.py

@@ -0,0 +1,142 @@
+"""Thurstone portfolio: the ability tilt as an online estimator.
+
+Weights are the winning probabilities of a Thurstonian race among assets.
+Abilities are calibrated so that the race under a reference correlation
+``C_calib`` reproduces a target benchmark; the tilt then re-runs the race under
+the estimated correlation ``C_tilt``. ``partial_fit`` transports a fixed seed
+ensemble to the updated correlation, so weights move smoothly (low turnover).
+
+See the paper *Thurstone Portfolios: Long-Only Allocation by Inverting Winning
+Probabilities* for the theory (feasibility, redundancy consistency, the implied
+regularized objective, and the smoothness/turnover bound).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .base import BaseOnlinePortfolio
+from ._thurstone.ability import base_density
+from ._thurstone.calibrate import calibrate_diagonal, calibrate_one_factor
+from ._thurstone.covariance import market_betas, one_factor_corr
+from ._thurstone.diagonal import diagonal_portfolio
+from ._thurstone.transport import blend_correlation, transport_weights
+
+__all__ = ["ThurstonePortfolio"]
+
+
+def _pow2(n: int) -> int:
+    return 1 << int(np.ceil(np.log2(max(int(n), 2))))
+
+
+def _normalize(w) -> np.ndarray:
+    w = np.asarray(w, dtype=float)
+    s = w.sum()
+    return w / s if s > 0 else np.full(len(w), 1.0 / len(w))
+
+
+class ThurstonePortfolio(BaseOnlinePortfolio):
+    """Long-only Thurstone-portfolio estimator.
+
+    Parameters
+    ----------
+    target : {"diagonal", "equal"} or array, default "diagonal"
+        Benchmark the calibration reproduces under the reference correlation. An
+        array (e.g. capitalization weights) is used as-is.
+    calib : {"diagonal", "market"}, default "diagonal"
+        Reference correlation ``C_calib``: identity (independent) or a one-factor
+        market model fitted from the covariance.
+    phi : float in [0, 1], default 1.0
+        Correlation scale for the tilt: 0 reproduces the benchmark, 1 uses the
+        full estimated correlation.
+    n_paths : int, default 16384
+        Monte-Carlo seed budget (rounded up to a power of two).
+    n_quad : int, default 16
+        Gauss--Hermite nodes for one-factor calibration.
+    seed : int, default 42
+        Seed for the fixed path ensemble.
+    covariance : estimator or None, default None
+        Online covariance estimator (``partial_fit`` / ``covariance_``). None uses
+        a built-in EWMA with ``halflife``.
+    halflife : float, default 60.0
+        EWMA halflife when ``covariance is None``.
+    """
+
+    def __init__(
+        self,
+        *,
+        target="diagonal",
+        calib: str = "diagonal",
+        phi: float = 1.0,
+        n_paths: int = 1 << 14,
+        n_quad: int = 16,
+        seed: int = 42,
+        covariance_estimator=None,
+        halflife: float = 60.0,
+    ):
+        super().__init__(covariance_estimator=covariance_estimator, halflife=halflife)
+        self.target = target
+        self.calib = calib
+        self.phi = phi
+        self.n_paths = n_paths
+        self.n_quad = n_quad
+        self.seed = seed
+        # persistent state set in _cold_start
+        self._seeds = None
+        self._ability = None
+        self._C_calib = None
+        self._target_w = None
+        self._betas = None
+
+    # ------------------------------------------------------------- helpers
+    def _resolve_target(self, cov: np.ndarray) -> np.ndarray:
+        n = cov.shape[0]
+        if isinstance(self.target, str):
+            if self.target == "diagonal":
+                return diagonal_portfolio(cov)
+            if self.target == "equal":
+                return np.full(n, 1.0 / n)
+            raise ValueError(f"unknown target {self.target!r}")
+        return _normalize(self.target)
+
+    # ------------------------------------------------------- estimator hooks
+    def _cold_start(self, cov: np.ndarray) -> None:
+        if not 0.0 <= self.phi <= 1.0:
+            raise ValueError("phi must lie in [0, 1].")
+        n = cov.shape[0]
+        base = base_density()
+        tgt = self._resolve_target(cov)
+        self._target_w = tgt
+
+        if self.calib == "diagonal":
+            self._betas = np.zeros(n)
+            self._C_calib = np.eye(n)
+            self._ability = calibrate_diagonal(tgt, base=base)
+        elif self.calib == "market":
+            b = market_betas(cov, weights=tgt)
+            self._betas = b
+            self._C_calib = one_factor_corr(b)
+            self._ability = calibrate_one_factor(tgt, b, base=base, n_quad=self.n_quad)
+        else:
+            raise ValueError(f"unknown calib {self.calib!r} (use 'diagonal' or 'market')")
+
+        rng = np.random.default_rng(self.seed)
+        self._seeds = rng.standard_normal((_pow2(self.n_paths), n))
+        self._online_update(cov)
+
+    def _online_update(self, cov: np.ndarray) -> None:
+        C_tilt = blend_correlation(self._C_calib, cov, self.phi)
+        self._weights = transport_weights(self._ability, C_tilt, self._seeds)
+
+    # --------------------------------------------------- fitted attributes
+    @property
+    def ability_(self) -> np.ndarray:
+        return self._ability
+
+    @property
+    def betas_(self) -> np.ndarray:
+        return self._betas
+
+    @property
+    def target_(self) -> np.ndarray:
+        return self._target_w

allocation/universe.py

@@ -0,0 +1,22 @@
+"""Keyed dynamic-universe support (design placeholder).
+
+skfolio handles a changing asset set the batch way (NaN handling, pre-selection,
+running on complete subsets). For a streaming estimator over a reconstituting
+universe (index additions/deletions, listings/delistings) we instead want
+per-asset state keyed by asset id, carried across ``partial_fit`` steps -- the
+approach taken by the ``precise`` package (``keyed`` / ``DynamicUniverse``).
+
+The common-seed transport composes naturally with this: a continuing asset keeps
+its seed column (so its weight stays smooth), a new asset gets a fresh column,
+and a delisted asset's column is dropped. This module will hold that keyed-state
+machinery; it is not wired into the estimators yet.
+
+TODO:
+- KeyedUniverse: maintain id -> column maps and per-asset persistent seed columns.
+- Wrap BaseOnlinePortfolio so fit/partial_fit accept a DataFrame (columns = ids)
+  and reconcile the abilities / seeds / covariance state on universe changes.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []