quantred 2.4.0__py3-none-any.whl

quantred/portfolio/allocator.py

@@ -0,0 +1,135 @@
+"""Constraint-solver portfolio allocation - because "put it all on the one with the
+highest score" is a strategy, just not a good one.
+
+Given a set of candidate symbols, each with a *score* (a higher score = more
+attractive, however the caller chooses to define it - expected return, signal
+strength, momentum, inverse volatility, ...), decide how to weight a portfolio
+across them subject to hard constraints:
+
+* invest at most 100% of capital,
+* hold at most ``max_positions`` names (cardinality),
+* cap any single name at ``max_weight`` and floor a *held* name at ``min_weight``.
+
+This is a small mixed-integer program solved with Google OR-Tools. Binary
+"is this name held?" variables enforce the cardinality and min-weight-if-held
+constraints; continuous weight variables carry the allocation.
+
+OR-Tools is an optional dependency (``portfolio`` extra) and is imported lazily,
+so the base install stays lean.
+"""
+
+import logging
+from dataclasses import dataclass
+from typing import List
+
+from quantred.utils.numeric import round_quantity
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Candidate:
+    """A symbol eligible for allocation."""
+
+    symbol: str
+    score: float  # higher = more attractive (caller-defined factor)
+    price: float
+
+
+@dataclass
+class Allocation:
+    """A solved allocation for one symbol."""
+
+    symbol: str
+    weight: float  # fraction of capital [0, 1]
+    dollars: float
+    shares: float
+
+
+class PortfolioAllocator:
+    """Weights positions across candidates via a MIP constraint solver."""
+
+    def __init__(
+        self,
+        max_positions: int = 5,
+        max_weight: float = 0.25,
+        min_weight: float = 0.0,
+        allow_fractional_shares: bool = False,
+    ):
+        if not 0 < max_weight <= 1:
+            raise ValueError("max_weight must be in (0, 1]")
+        if not 0 <= min_weight <= max_weight:
+            raise ValueError("min_weight must be in [0, max_weight]")
+        self.max_positions = max_positions
+        self.max_weight = max_weight
+        self.min_weight = min_weight
+        self.allow_fractional_shares = allow_fractional_shares
+
+    def allocate(self, candidates: List[Candidate], capital: float) -> List[Allocation]:
+        """Return the optimal allocation across ``candidates`` for ``capital``.
+
+        Only candidates with a positive score are considered (a non-positive
+        score never improves the objective and would only consume a slot).
+        """
+        eligible = [c for c in candidates if c.score > 0 and c.price > 0]
+        if not eligible or capital <= 0:
+            return []
+
+        solver = self._make_solver()
+        weights, selected = self._build_model(solver, eligible)
+
+        status = solver.Solve()
+        if status not in (solver.OPTIMAL, solver.FEASIBLE):
+            logger.warning("Portfolio solver returned no usable solution (status=%s)", status)
+            return []
+
+        allocations = []
+        for candidate, weight_var, select_var in zip(eligible, weights, selected):
+            weight = weight_var.solution_value()
+            if select_var.solution_value() < 0.5 or weight <= 1e-9:
+                continue
+            dollars = weight * capital
+            allocations.append(
+                Allocation(
+                    symbol=candidate.symbol,
+                    weight=weight,
+                    dollars=dollars,
+                    shares=round_quantity(dollars / candidate.price, self.allow_fractional_shares),
+                )
+            )
+        return sorted(allocations, key=lambda a: a.weight, reverse=True)
+
+    # ------------------------------------------------------------------ #
+    # Model construction
+    # ------------------------------------------------------------------ #
+    def _build_model(self, solver, candidates: List[Candidate]):
+        weights, selected = [], []
+        for candidate in candidates:
+            weight = solver.NumVar(0.0, self.max_weight, f"w_{candidate.symbol}")
+            select = solver.BoolVar(f"x_{candidate.symbol}")
+            # A name's weight is bounded by its selection flag (0 weight if unheld),
+            # and floored at min_weight when held.
+            solver.Add(weight <= self.max_weight * select)
+            solver.Add(weight >= self.min_weight * select)
+            weights.append(weight)
+            selected.append(select)
+
+        solver.Add(solver.Sum(weights) <= 1.0)  # invest <= 100%
+        solver.Add(solver.Sum(selected) <= self.max_positions)  # cardinality cap
+
+        solver.Maximize(solver.Sum(c.score * w for c, w in zip(candidates, weights)))
+        return weights, selected
+
+    @staticmethod
+    def _make_solver():
+        try:
+            from ortools.linear_solver import pywraplp
+        except ImportError as exc:  # pragma: no cover - depends on optional extra
+            from quantred.utils.extras import missing_extra_message
+
+            raise RuntimeError(missing_extra_message("The portfolio allocator", "portfolio")) from exc
+
+        solver = pywraplp.Solver.CreateSolver("CBC")
+        if solver is None:  # pragma: no cover
+            raise RuntimeError("Could not create an OR-Tools CBC solver")
+        return solver

quantred/portfolio/benchmark.py

@@ -0,0 +1,109 @@
+"""The benchmark as a portfolio: loading ``w_B``, and reverse optimization.
+
+Everywhere else in the stack a benchmark is a *return series* (e.g. SPY closes) -
+betas and residual vols regress against it. This module is the other half: a
+benchmark as a *holdings vector*, which is what makes "tracking error" the real
+thing (``ψ = √(w_aᵀΣw_a)``, active weights ``w_a = w − w_B``) instead of the total
+volatility of a cash-relative book. Pure, dependency-light functions - no data
+fetching here (that's the caller's job); this module only turns a raw weights
+mapping into something the optimizer and reverse-optimization report can use.
+"""
+
+import csv
+import json
+from pathlib import Path
+from typing import Dict, Iterable, Mapping, Tuple, Union
+
+from quantred.risk.base import RiskMatrix
+
+
+def load_benchmark_weights(
+    source: Union[str, Mapping[str, float]], symbols: Iterable[str]
+) -> Dict[str, float]:
+    """Load ``w_B`` from ``"equal"``, a holdings file, or a mapping given directly.
+
+    The mapping form exists because not every caller has a filesystem to point at. The
+    agent surface passes weights as data and is deliberately never given a *path*: a
+    parameter that names a file is a file-read primitive, and this surface's whole
+    premise is that it holds no capability it was not handed. Same normalization either
+    way, so a book loaded from disk and the same book passed inline cannot disagree.
+
+    A file is CSV (``symbol,weight`` header + rows) or JSON (``{"symbol": weight}``).
+    Cap-proxy weighting (shares outstanding) is deliberately not supported in v1 -
+    ``equal`` + a user-supplied file covers it for now.
+
+    Always renormalized to sum to 1: a benchmark that isn't fully invested (holds
+    cash) is folded pro-rata into its named holdings rather than modeled as a
+    genuine zero-variance asset - a documented v1 simplification, not a hidden
+    one - callers that care can compare against ``raw_weight_sum``
+    before renormalization.
+    """
+    symbols = list(symbols)
+    if not isinstance(source, str):
+        weights = {str(k): float(v) for k, v in dict(source).items()}
+        total = sum(weights.values())
+        if total <= 0:
+            raise ValueError("benchmark holdings mapping has no positive weight")
+        return {s: w / total for s, w in weights.items()}
+
+    if source == "equal":
+        if not symbols:
+            return {}
+        w = 1.0 / len(symbols)
+        return {s: w for s in symbols}
+
+    path = Path(source)
+    if not path.exists():
+        raise ValueError(f"benchmark holdings source {source!r} is neither 'equal' nor an existing file")
+
+    if path.suffix.lower() == ".json":
+        raw = json.loads(path.read_text())
+        weights = {str(k): float(v) for k, v in raw.items()}
+    elif path.suffix.lower() == ".csv":
+        weights = {}
+        with path.open(newline="") as fh:
+            for row in csv.DictReader(fh):
+                weights[str(row["symbol"]).strip()] = float(row["weight"])
+    else:
+        raise ValueError(f"benchmark holdings file must be .csv or .json, got {path.suffix!r}")
+
+    total = sum(weights.values())
+    if total <= 0:
+        raise ValueError(f"benchmark holdings file {source!r} has no positive weight")
+    return {s: w / total for s, w in weights.items()}
+
+
+def restrict_and_renormalize(
+    weights: Dict[str, float], covered_symbols: Iterable[str]
+) -> Tuple[Dict[str, float], float]:
+    """Restrict ``w_B`` to names Σ actually covers, and renormalize to sum to 1.
+
+    Reverse optimization and tracking error need Σ to span the benchmark; when it
+    only spans the trading universe, the sanctioned v1 alternative to extending
+    the panel is this - restrict and renormalize, *loudly*: returns the coverage
+    fraction (of raw weight mass) alongside
+    the restricted weights, so a caller can warn when it's materially less than 1.
+    """
+    covered = set(covered_symbols)
+    raw_total = sum(weights.values())
+    kept = {s: w for s, w in weights.items() if s in covered}
+    kept_total = sum(kept.values())
+    coverage = (kept_total / raw_total) if raw_total > 0 else 0.0
+    if kept_total <= 0:
+        return {}, coverage
+    return {s: w / kept_total for s, w in kept.items()}, coverage
+
+
+def implied_returns(benchmark_weights: Dict[str, float], risk: RiskMatrix, mu_b: float) -> Dict[str, float]:
+    """Reverse optimization: the consensus returns for which
+    the benchmark ``w_B`` is itself mean-variance optimal.
+
+    ``β = Σw_B/(w_Bᵀ Σ w_B)`` (the one canonical benchmark beta -
+    :meth:`RiskMatrix.implied_beta`), ``μ = β·μ_B`` for a stated benchmark premium
+    ``μ_B``. Feeding ``μ`` back into :meth:`~quantred.portfolio.optimizer.MeanVarianceOptimizer.optimize`
+    with this same ``w_B`` and zero cost returns ``w = w_B`` exactly - the sharpest
+    integration test available, and the corollary this function exists to enable:
+    our alphas are *deviations from* this consensus.
+    """
+    beta = risk.implied_beta(benchmark_weights)
+    return {sym: float(beta[sym] * mu_b) for sym in risk.symbols}