alpha-engine-lib 0.44.0__tar.gz → 0.46.0__tar.gz

{alpha_engine_lib-0.44.0 → alpha_engine_lib-0.46.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alpha-engine-lib
-Version: 0.44.0
+Version: 0.46.0
 Summary: Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, and S3-conditional-PUT writer locks. Full surface documented in README.
 Author: Brian McMahon
 License: Proprietary
@@ -14,6 +14,8 @@ Requires-Dist: eval_type_backport>=0.2.0; python_version < "3.10"
 Provides-Extra: arcticdb
 Requires-Dist: arcticdb>=6.11; extra == "arcticdb"
 Requires-Dist: pandas>=2.0; extra == "arcticdb"
+Provides-Extra: quant
+Requires-Dist: numpy>=1.24; extra == "quant"
 Provides-Extra: flow-doctor
 Requires-Dist: flow-doctor[diagnosis,s3]<0.5.0,>=0.4.0; extra == "flow-doctor"
 Provides-Extra: rag
@@ -248,6 +250,21 @@ Rotates across `(instance_type × subnet)` combinations on `InsufficientInstance
 
 `universe_writer_lock(writer_id, ttl_seconds=3600)` context manager that uses `PutObject(IfNoneMatch="*")` to claim a single-writer lease on `s3://alpha-engine-research/locks/universe-writer.lock`. The first writer's conditional PUT succeeds; subsequent writers get `LockHeldByAnotherWriterError` carrying the live `LockHolder` body (writer_id + started_at + ttl_epoch + hostname + pid) for operator diagnostics. Soft-TTL self-recovery deletes-and-re-acquires when the on-disk lock's `ttl_epoch` has elapsed; the operator-side S3 lifecycle on `locks/` (expires-after-days=1) is the hard backstop. Release on context exit is best-effort and never masks an inner exception. Closes the producer-side half of the same single-writer-per-resource invariant the SF MutualExclusionGuard (DynamoDB-side) covers at the Step Function entry point; the lib lift is the chokepoint that picks up the third adopter for free (predictor weight-promote, backfill loops, etc.).
 
+### `quant` — portfolio analytics engine (factor risk, VaR/CVaR, attribution, returns)
+
+The shared institutional-analytics engine: pure, front-end- and data-source-agnostic functions that *describe and measure* a portfolio (performance, risk, attribution) with **no advisory logic** — it sits on the "analytics, not advice" side of the line. Lifted from robodashboard's `analytics/` after the 2026-06-03 cross-repo leverage audit, so both the alpha-engine fleet and robodashboard consume one engine instead of parallel reimplementations. Import the submodule you need (the package keeps no eager imports, so the stdlib-only modules import without numpy):
+
+- **`quant.factor_risk`** — statistical factor risk model `Σ = B·F·Bᵀ + D`: `estimate_factor_model` (time-series factor-ETF / Fama-MacBeth loadings), `portfolio_risk` (ex-ante vol + factor/idio split + per-factor variance contribution), `tracking_error`, `benchmark_exposure`, and a numpy-only `ledoit_wolf_cov` (no sklearn). The estimator-agnostic consumption core (`portfolio_risk`/`tracking_error`) consumes any `FactorRiskModel` (B, F, D). **Needs numpy** — `pip install "alpha-engine-lib[quant]"`.
+- **`quant.risk_measures`** — parametric (Gaussian, Acklam inverse-normal, no scipy) + historical VaR & CVaR, as positive loss fractions at a horizon (stdlib).
+- **`quant.riskstats`** — `volatility`, `sharpe_ratio`, `sortino_ratio`, `max_drawdown` (stdlib).
+- **`quant.returns`** — `xirr` (money-weighted, Newton + bisection), `time_weighted_return` (GIPS), `cumulative_return`, `annualize` (stdlib).
+- **`quant.attribution`** — single-period Brinson-Fachler decomposition (`brinson_fachler`) + multi-period Cariño linking (`link_periods`) (stdlib).
+
+```python
+from alpha_engine_lib.quant.risk_measures import historical_cvar
+from alpha_engine_lib.quant.factor_risk import estimate_factor_model, portfolio_risk
+```
+
 ## How it's used
 
 All six Nous Ergon module repos depend on this lib:

{alpha_engine_lib-0.44.0 → alpha_engine_lib-0.46.0}/README.md

@@ -219,6 +219,21 @@ Rotates across `(instance_type × subnet)` combinations on `InsufficientInstance
 
 `universe_writer_lock(writer_id, ttl_seconds=3600)` context manager that uses `PutObject(IfNoneMatch="*")` to claim a single-writer lease on `s3://alpha-engine-research/locks/universe-writer.lock`. The first writer's conditional PUT succeeds; subsequent writers get `LockHeldByAnotherWriterError` carrying the live `LockHolder` body (writer_id + started_at + ttl_epoch + hostname + pid) for operator diagnostics. Soft-TTL self-recovery deletes-and-re-acquires when the on-disk lock's `ttl_epoch` has elapsed; the operator-side S3 lifecycle on `locks/` (expires-after-days=1) is the hard backstop. Release on context exit is best-effort and never masks an inner exception. Closes the producer-side half of the same single-writer-per-resource invariant the SF MutualExclusionGuard (DynamoDB-side) covers at the Step Function entry point; the lib lift is the chokepoint that picks up the third adopter for free (predictor weight-promote, backfill loops, etc.).
 
+### `quant` — portfolio analytics engine (factor risk, VaR/CVaR, attribution, returns)
+
+The shared institutional-analytics engine: pure, front-end- and data-source-agnostic functions that *describe and measure* a portfolio (performance, risk, attribution) with **no advisory logic** — it sits on the "analytics, not advice" side of the line. Lifted from robodashboard's `analytics/` after the 2026-06-03 cross-repo leverage audit, so both the alpha-engine fleet and robodashboard consume one engine instead of parallel reimplementations. Import the submodule you need (the package keeps no eager imports, so the stdlib-only modules import without numpy):
+
+- **`quant.factor_risk`** — statistical factor risk model `Σ = B·F·Bᵀ + D`: `estimate_factor_model` (time-series factor-ETF / Fama-MacBeth loadings), `portfolio_risk` (ex-ante vol + factor/idio split + per-factor variance contribution), `tracking_error`, `benchmark_exposure`, and a numpy-only `ledoit_wolf_cov` (no sklearn). The estimator-agnostic consumption core (`portfolio_risk`/`tracking_error`) consumes any `FactorRiskModel` (B, F, D). **Needs numpy** — `pip install "alpha-engine-lib[quant]"`.
+- **`quant.risk_measures`** — parametric (Gaussian, Acklam inverse-normal, no scipy) + historical VaR & CVaR, as positive loss fractions at a horizon (stdlib).
+- **`quant.riskstats`** — `volatility`, `sharpe_ratio`, `sortino_ratio`, `max_drawdown` (stdlib).
+- **`quant.returns`** — `xirr` (money-weighted, Newton + bisection), `time_weighted_return` (GIPS), `cumulative_return`, `annualize` (stdlib).
+- **`quant.attribution`** — single-period Brinson-Fachler decomposition (`brinson_fachler`) + multi-period Cariño linking (`link_periods`) (stdlib).
+
+```python
+from alpha_engine_lib.quant.risk_measures import historical_cvar
+from alpha_engine_lib.quant.factor_risk import estimate_factor_model, portfolio_risk
+```
+
 ## How it's used
 
 All six Nous Ergon module repos depend on this lib:

{alpha_engine_lib-0.44.0 → alpha_engine_lib-0.46.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "alpha-engine-lib"
-version = "0.44.0"
+version = "0.46.0"
 description = "Shared utilities for the Alpha Engine modules: preflight, logging, ArcticDB, dates, decision capture, cost telemetry, Anthropic payload chokepoint, artifact freshness, RAG, agent schemas, SSM secrets, Telegram + SNS alerts, EC2 spot resilience, SSM log-capture, SSM dispatcher, Step-Functions execution-state projection, and S3-conditional-PUT writer locks. Full surface documented in README."
 readme = "README.md"
 # EC2 still runs Python 3.9 on the always-on micro instance (boto3 drops
@@ -30,6 +30,10 @@ dependencies = [
 
 [project.optional-dependencies]
 arcticdb = ["arcticdb>=6.11", "pandas>=2.0"]
+# Quantitative portfolio analytics (alpha_engine_lib.quant). Only the
+# factor-risk module needs numpy; the VaR/CVaR, riskstats, returns, and
+# attribution modules are pure stdlib and import without this extra.
+quant = ["numpy>=1.24"]
 flow_doctor = ["flow-doctor[diagnosis,s3]>=0.4.0,<0.5.0"]
 rag = [
     "psycopg2-binary>=2.9",

{alpha_engine_lib-0.44.0 → alpha_engine_lib-0.46.0}/src/alpha_engine_lib/__init__.py

@@ -1,3 +1,3 @@
 """alpha-engine-lib — shared utilities for Alpha Engine modules."""
 
-__version__ = "0.44.0"
+__version__ = "0.46.0"

{alpha_engine_lib-0.44.0 → alpha_engine_lib-0.46.0}/src/alpha_engine_lib/pipeline_status/registry.py

@@ -69,6 +69,8 @@ WAIT_GROUPING: Final[dict[str, str]] = {
     "WaitForRAGIngestion": "RAGIngestion",
     "WaitForPredictorTraining": "PredictorTraining",
     "WaitForBacktester": "Backtester",
+    "WaitForPredictorBacktest": "PredictorBacktest",
+    "WaitForPortfolioOptimizerBacktest": "PortfolioOptimizerBacktest",
     "WaitForParity": "Parity",
     "WaitForEvaluator": "Evaluator",
     "WaitForSaturdayHealthCheck": "SaturdayHealthCheck",
@@ -254,6 +256,18 @@ STATE_TO_ARCHIVE_PAGE: Final[dict[str, Union[ArchivePageRef, ArtifactReason]]] =
         page="21_Backtester_Evaluator_Archive",
         artifact_label="Backtester consolidated report",
     ),
+    # L4472 phase-split (2026-05-31): the monolithic Backtester state was
+    # decomposed into Backtester (simulate) → PredictorBacktest → Portfolio-
+    # OptimizerBacktest. All three write into the same backtest/{date}/ prefix
+    # surfaced on the consolidated evaluator archive page.
+    "PredictorBacktest": ArchivePageRef(
+        page="21_Backtester_Evaluator_Archive",
+        artifact_label="Predictor backtest + Phase 4 report",
+    ),
+    "PortfolioOptimizerBacktest": ArchivePageRef(
+        page="21_Backtester_Evaluator_Archive",
+        artifact_label="Portfolio-optimizer / cov / gamma sweep report",
+    ),
     "Parity": ArchivePageRef(
         page="3_Analysis",
         artifact_label="Parity replay diff",

alpha_engine_lib-0.46.0/src/alpha_engine_lib/quant/__init__.py

@@ -0,0 +1,25 @@
+"""Quantitative portfolio analytics — pure, front-end- and data-source-agnostic.
+
+The shared institutional-analytics engine consumed across the fleet (predictor,
+backtester, robodashboard). Every module is dependency-light and unit-testable in
+isolation, and *describes/measures* a portfolio (performance, risk, attribution)
+with **no advisory logic** — it sits on the "analytics, not advice" side of the
+line.
+
+Modules (import the submodule you need — the package keeps no eager imports so the
+stdlib-only modules stay importable without numpy):
+
+  - ``factor_risk``    — Σ=B·F·Bᵀ+D ex-ante risk + tracking error (**needs numpy**;
+                          install ``alpha-engine-lib[quant]``)
+  - ``risk_measures``  — parametric + historical VaR / CVaR (stdlib)
+  - ``riskstats``      — volatility, Sharpe, Sortino, max drawdown (stdlib)
+  - ``returns``        — XIRR (money-weighted) + time-weighted return (stdlib)
+  - ``attribution``    — Brinson-Fachler decomposition + Cariño linking (stdlib)
+
+Example::
+
+    from alpha_engine_lib.quant.risk_measures import historical_cvar
+    from alpha_engine_lib.quant.factor_risk import estimate_factor_model, portfolio_risk
+"""
+
+from __future__ import annotations

alpha_engine_lib-0.46.0/src/alpha_engine_lib/quant/attribution.py

@@ -0,0 +1,183 @@
+"""Performance attribution — Brinson-Fachler decomposition + Cariño linking.
+
+Pure stdlib, data-source-agnostic (takes plain group weight/return dicts, not a
+broker client), so it's unit-testable in isolation and reusable unchanged across
+front ends. This *explains* a portfolio's active return vs a benchmark — where
+the over/under-performance came from — without ever prescribing a trade.
+
+**Single period (Brinson-Fachler).** For each group *i* (typically a sector),
+decompose the active return ``R_p − R_b`` into:
+
+  - **Allocation** ``(w_p,i − w_b,i) · (r_b,i − R_b)`` — did over/under-weighting a
+    group (vs its benchmark weight) help, given how that group did vs the whole
+    benchmark? (The Fachler refinement subtracts the total benchmark return
+    ``R_b`` so allocation rewards over-weighting *out-performing* groups.)
+  - **Selection** ``w_b,i · (r_p,i − r_b,i)`` — did picks within a group beat the
+    group's benchmark, at benchmark weight?
+  - **Interaction** ``(w_p,i − w_b,i) · (r_p,i − r_b,i)`` — the cross term.
+
+The three effects summed over all groups equal the arithmetic active return.
+
+**Multi-period (Cariño linking).** Arithmetic single-period effects don't simply
+add across periods because returns compound geometrically. Cariño (1999) scales
+each period's effects by ``k_t / k`` so the linked effects sum *exactly* to the
+geometric cumulative active return — the institutional standard for chaining a
+Brinson attribution through time.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+
+# Returns within ~1e-12 of each other are treated as equal for the linking-limit
+# branches (where the divided-difference coefficient hits its L'Hôpital limit).
+_EPS = 1e-12
+
+
+@dataclass(frozen=True)
+class GroupAttribution:
+    """Per-group Brinson-Fachler effects (all in return-fraction units)."""
+
+    group: str
+    allocation: float
+    selection: float
+    interaction: float
+
+    @property
+    def total(self) -> float:
+        return self.allocation + self.selection + self.interaction
+
+
+@dataclass(frozen=True)
+class BrinsonResult:
+    """A single- or linked-period attribution: per-group effects + totals.
+
+    ``portfolio_return`` / ``benchmark_return`` are the (cumulative, for a linked
+    result) totals; ``active_return`` is their difference and equals
+    ``total_effect`` up to floating-point error.
+    """
+
+    groups: list[GroupAttribution] = field(default_factory=list)
+    allocation: float = 0.0
+    selection: float = 0.0
+    interaction: float = 0.0
+    portfolio_return: float = 0.0
+    benchmark_return: float = 0.0
+
+    @property
+    def active_return(self) -> float:
+        return self.portfolio_return - self.benchmark_return
+
+    @property
+    def total_effect(self) -> float:
+        return self.allocation + self.selection + self.interaction
+
+
+def brinson_fachler(
+    weights_p: dict[str, float],
+    returns_p: dict[str, float],
+    weights_b: dict[str, float],
+    returns_b: dict[str, float],
+) -> BrinsonResult:
+    """Single-period Brinson-Fachler attribution over the union of groups.
+
+    Args are group → weight / group → return maps for the portfolio (``_p``) and
+    benchmark (``_b``). Weights are fractions of their respective totals. The
+    group sets need not match: a group the benchmark doesn't hold defaults its
+    benchmark return to the overall benchmark return ``R_b`` (neutral allocation
+    baseline); a group the portfolio doesn't hold defaults its portfolio return
+    to that group's benchmark return (zero selection). Missing weights default to
+    0.
+
+    Totals: ``R_p = Σ w_p,i·r_p,i``, ``R_b = Σ w_b,i·r_b,i`` over the groups given
+    — so for the decomposition to tie to the true portfolio/benchmark returns,
+    the weights should each sum to ~1 across the groups passed in.
+    """
+    groups = sorted(set(weights_p) | set(returns_p) | set(weights_b) | set(returns_b))
+
+    r_b_total = sum(weights_b.get(g, 0.0) * returns_b.get(g, 0.0) for g in groups)
+    r_p_total = sum(weights_p.get(g, 0.0) * returns_p.get(g, 0.0) for g in groups)
+
+    per_group: list[GroupAttribution] = []
+    for g in groups:
+        wp = weights_p.get(g, 0.0)
+        wb = weights_b.get(g, 0.0)
+        # Benchmark return for a group the benchmark doesn't hold → the overall
+        # benchmark return (so its allocation baseline is neutral). Portfolio
+        # return for a group the portfolio doesn't hold → that group's benchmark
+        # return (so selection is zero — you can't pick within what you don't own).
+        rb = returns_b.get(g, r_b_total)
+        rp = returns_p.get(g, rb)
+        allocation = (wp - wb) * (rb - r_b_total)
+        selection = wb * (rp - rb)
+        interaction = (wp - wb) * (rp - rb)
+        per_group.append(GroupAttribution(g, allocation, selection, interaction))
+
+    return BrinsonResult(
+        groups=per_group,
+        allocation=sum(a.allocation for a in per_group),
+        selection=sum(a.selection for a in per_group),
+        interaction=sum(a.interaction for a in per_group),
+        portfolio_return=r_p_total,
+        benchmark_return=r_b_total,
+    )
+
+
+def _carino_coefficient(r_p: float, r_b: float) -> float:
+    """Cariño linking coefficient ``(ln(1+r_p) − ln(1+r_b)) / (r_p − r_b)``.
+
+    At ``r_p == r_b`` this is the L'Hôpital limit ``1 / (1 + r)``. Requires
+    ``1 + r > 0`` for both (a ≤ −100% period return has no log).
+    """
+    if 1.0 + r_p <= 0.0 or 1.0 + r_b <= 0.0:
+        raise ValueError("Cariño linking requires period returns > -100%")
+    if abs(r_p - r_b) < _EPS:
+        return 1.0 / (1.0 + r_b)
+    return (math.log(1.0 + r_p) - math.log(1.0 + r_b)) / (r_p - r_b)
+
+
+def link_periods(periods: list[BrinsonResult]) -> BrinsonResult:
+    """Cariño-link a sequence of single-period attributions into one result.
+
+    Each period's effects are scaled by ``k_t / k`` so the linked per-group and
+    total effects sum exactly to the **geometric** cumulative active return
+    ``(∏(1+r_p,t) − 1) − (∏(1+r_b,t) − 1)``. Group identities are matched by name
+    across periods (a group absent in a period contributes 0 that period).
+
+    Single period → returned unchanged. Empty → an all-zero result. Raises
+    ``ValueError`` if any period return is ≤ −100% (no log).
+    """
+    if not periods:
+        return BrinsonResult()
+    if len(periods) == 1:
+        return periods[0]
+
+    cum_p = math.prod(1.0 + p.portfolio_return for p in periods) - 1.0
+    cum_b = math.prod(1.0 + p.benchmark_return for p in periods) - 1.0
+    k_overall = _carino_coefficient(cum_p, cum_b)
+
+    # Accumulate scaled effects per group and for the totals.
+    alloc: dict[str, float] = {}
+    select: dict[str, float] = {}
+    interact: dict[str, float] = {}
+    for p in periods:
+        k_t = _carino_coefficient(p.portfolio_return, p.benchmark_return)
+        scale = k_t / k_overall
+        for ga in p.groups:
+            alloc[ga.group] = alloc.get(ga.group, 0.0) + ga.allocation * scale
+            select[ga.group] = select.get(ga.group, 0.0) + ga.selection * scale
+            interact[ga.group] = interact.get(ga.group, 0.0) + ga.interaction * scale
+
+    per_group = [
+        GroupAttribution(g, alloc.get(g, 0.0), select.get(g, 0.0), interact.get(g, 0.0))
+        for g in sorted(alloc.keys() | select.keys() | interact.keys())
+    ]
+    return BrinsonResult(
+        groups=per_group,
+        allocation=sum(a.allocation for a in per_group),
+        selection=sum(a.selection for a in per_group),
+        interaction=sum(a.interaction for a in per_group),
+        portfolio_return=cum_p,
+        benchmark_return=cum_b,
+    )

alpha_engine_lib-0.46.0/src/alpha_engine_lib/quant/factor_risk.py

@@ -0,0 +1,207 @@
+"""Statistical factor risk model — ex-ante portfolio risk + tracking error.
+
+Pure numpy (no sklearn/scipy), data-source-agnostic. Regresses each holding's
+return series on a set of **factor return series** (e.g. market + style-ETF
+spreads, or universe-wide Fama-MacBeth factor returns) to recover loadings ``B``
+and idiosyncratic variance ``D``; ``F`` is the (Ledoit-Wolf-shrunk) factor-return
+covariance. The structural covariance
+
+    Σ = B · F · Bᵀ + D
+
+then gives the portfolio's **ex-ante volatility**, its split into **factor vs
+idiosyncratic** risk, **per-factor risk contributions**, and **tracking error**
+vs a benchmark. Descriptive risk analytics — no advice, no trade.
+
+The consumption layer (``portfolio_risk`` / ``tracking_error`` / decomposition)
+is estimator-agnostic: it consumes any ``FactorRiskModel`` (B, F, D). Two
+estimators are supported as factor *sources*: the time-series factor-ETF
+regression here (``estimate_factor_model``), and — once wired — a universe-wide
+cross-sectional Fama-MacBeth build (the alpha-engine predictor's ``risk_model``).
+Both feed the same Σ=BFBᵀ+D core. See alpha-engine-lib OVERVIEW for the leverage
+rationale.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+import numpy as np
+
+_TRADING_DAYS = 252
+
+
+def ledoit_wolf_cov(observations: np.ndarray, *, shrinkage: str = "ledoit_wolf") -> np.ndarray:
+    """Covariance of an ``(n_obs, k)`` matrix, optionally Ledoit-Wolf shrunk.
+
+    ``"ledoit_wolf"`` (default) shrinks the MLE sample covariance toward a scaled
+    identity (Ledoit & Wolf 2004), which keeps a small-/noisy-sample factor
+    covariance well-conditioned. ``"sample"`` returns the plain (n−1) sample
+    covariance. Shrinkage intensity is estimated from the data, so for a large,
+    clean sample it ≈ the sample covariance.
+    """
+    X = np.asarray(observations, dtype=float)
+    n, p = X.shape
+    Xc = X - X.mean(axis=0, keepdims=True)
+    if shrinkage == "sample" or n < 2 or p < 2:
+        return (Xc.T @ Xc) / max(n - 1, 1)
+
+    sample = (Xc.T @ Xc) / n  # MLE divisor (Ledoit-Wolf convention)
+    mu = np.trace(sample) / p
+    target = mu * np.eye(p)
+    d2 = float(np.sum((sample - target) ** 2) / p)
+    if d2 == 0.0:
+        return sample
+    # b̄² — mean squared error of the per-observation outer products vs the sample.
+    b_sum = 0.0
+    for t in range(n):
+        xt = Xc[t][:, None]
+        b_sum += float(np.sum((xt @ xt.T - sample) ** 2))
+    b2 = min(b_sum / (n * n) / p, d2)
+    shrink = b2 / d2  # → 0 for a clean sample, → 1 when the sample is all noise
+    return shrink * target + (1.0 - shrink) * sample
+
+
+def _ols(y: np.ndarray, factors: np.ndarray) -> tuple[np.ndarray, float]:
+    """OLS of ``y`` on ``factors`` (+ intercept). Returns (betas, residual variance)."""
+    n = len(y)
+    design = np.column_stack([np.ones(n), factors])
+    coef, *_ = np.linalg.lstsq(design, y, rcond=None)
+    resid = y - design @ coef
+    dof = max(n - design.shape[1], 1)
+    return coef[1:], float(resid @ resid / dof)
+
+
+@dataclass(frozen=True)
+class FactorRiskModel:
+    """Estimated factor risk model: loadings B, idio variance D, factor cov F.
+
+    ``betas`` is ``(N, K)`` over ``tickers`` × ``factors``; ``idio_var`` is the
+    ``(N,)`` daily residual variance; ``factor_cov`` is the ``(K, K)`` daily
+    factor covariance. All variances are per-period (daily); annualization happens
+    in the risk functions via ``periods_per_year``.
+    """
+
+    factors: list[str]
+    tickers: list[str]
+    betas: np.ndarray
+    idio_var: np.ndarray
+    factor_cov: np.ndarray
+    periods_per_year: int = _TRADING_DAYS
+
+
+def _factor_matrix(factor_returns: dict[str, Sequence[float]]) -> tuple[list[str], np.ndarray]:
+    factors = list(factor_returns)
+    mat = np.column_stack([np.asarray(factor_returns[f], dtype=float) for f in factors])
+    return factors, mat
+
+
+def estimate_factor_model(
+    holding_returns: dict[str, Sequence[float]],
+    factor_returns: dict[str, Sequence[float]],
+    *,
+    shrinkage: str = "ledoit_wolf",
+    periods_per_year: int = _TRADING_DAYS,
+) -> FactorRiskModel:
+    """Fit loadings + idio variance per holding and the factor covariance.
+
+    ``holding_returns`` and ``factor_returns`` are ``{name: return_series}`` maps,
+    all aligned to the same ``n`` dates. Each holding is OLS-regressed on the
+    factor matrix (with intercept). Raises ``ValueError`` if the series lengths
+    disagree or there aren't enough observations to identify the factors.
+    """
+    factors, fmat = _factor_matrix(factor_returns)
+    n, k = fmat.shape
+    if n < k + 2:
+        raise ValueError(f"need ≥ {k + 2} observations for {k} factors, got {n}")
+
+    tickers: list[str] = []
+    betas: list[np.ndarray] = []
+    idio: list[float] = []
+    for ticker, series in holding_returns.items():
+        y = np.asarray(series, dtype=float)
+        if len(y) != n:
+            raise ValueError(f"{ticker} has {len(y)} returns, expected {n}")
+        b, rv = _ols(y, fmat)
+        tickers.append(ticker)
+        betas.append(b)
+        idio.append(rv)
+
+    return FactorRiskModel(
+        factors=factors,
+        tickers=tickers,
+        betas=np.array(betas).reshape(len(tickers), k),
+        idio_var=np.array(idio, dtype=float),
+        factor_cov=ledoit_wolf_cov(fmat, shrinkage=shrinkage),
+        periods_per_year=periods_per_year,
+    )
+
+
+def benchmark_exposure(benchmark_returns: Sequence[float], factor_returns: dict[str, Sequence[float]]) -> np.ndarray:
+    """Benchmark's factor exposure — OLS betas of its return series on the factors.
+
+    A diversified benchmark's idiosyncratic risk is ≈ 0, so only its factor
+    exposure is needed for tracking error.
+    """
+    _, fmat = _factor_matrix(factor_returns)
+    beta, _ = _ols(np.asarray(benchmark_returns, dtype=float), fmat)
+    return beta
+
+
+def _weight_vector(model: FactorRiskModel, weights: dict[str, float]) -> np.ndarray:
+    """Weights aligned to ``model.tickers``, renormalized to sum 1 over the covered set."""
+    w = np.array([float(weights.get(t, 0.0)) for t in model.tickers])
+    total = w.sum()
+    return w / total if total > 0 else w
+
+
+def portfolio_risk(model: FactorRiskModel, weights: dict[str, float]) -> dict:
+    """Ex-ante annualized risk of the weighted portfolio, decomposed.
+
+    Returns total / factor / idiosyncratic volatility (annualized), the
+    portfolio's net factor exposures (``Bᵀw``), and each factor's share of total
+    **variance** (``factor_pct_contrib`` sums to the factor share; ``idio_pct``
+    is the rest).
+    """
+    w = _weight_vector(model, weights)
+    ann = model.periods_per_year
+    x = model.betas.T @ w  # (K,) portfolio factor exposure
+    fx = model.factor_cov @ x
+    factor_var = float(x @ fx)
+    idio_var = float(np.sum(w**2 * model.idio_var))
+    total_var = factor_var + idio_var
+
+    contrib = x * fx  # per-factor variance contribution; Σ = factor_var
+    # NB: zip() without strict= (added 3.10) — the lib targets 3.9; the iterables
+    # are equal-length by construction (factors, contrib, x, active are all length K).
+    pct = {f: (float(c) / total_var if total_var > 0 else 0.0) for f, c in zip(model.factors, contrib)}
+    return {
+        "total_vol": float(np.sqrt(max(total_var, 0.0) * ann)),
+        "factor_vol": float(np.sqrt(max(factor_var, 0.0) * ann)),
+        "idio_vol": float(np.sqrt(max(idio_var, 0.0) * ann)),
+        "factor_exposures": {f: float(v) for f, v in zip(model.factors, x)},
+        "factor_pct_contrib": pct,
+        "idio_pct": (idio_var / total_var if total_var > 0 else 0.0),
+    }
+
+
+def tracking_error(model: FactorRiskModel, weights: dict[str, float], benchmark_exposures: np.ndarray) -> dict:
+    """Annualized tracking error (active risk) vs a benchmark.
+
+    Active factor exposure is ``Bᵀw − x_b``; the portfolio's idiosyncratic risk is
+    treated as fully active (a diversified benchmark contributes ≈ 0 idio). Also
+    returns the per-factor active exposures so you can see which tilts drive the
+    deviation from the benchmark.
+    """
+    w = _weight_vector(model, weights)
+    ann = model.periods_per_year
+    active = model.betas.T @ w - np.asarray(benchmark_exposures, dtype=float)
+    active_factor_var = float(active @ model.factor_cov @ active)
+    active_idio_var = float(np.sum(w**2 * model.idio_var))
+    te_var = active_factor_var + active_idio_var
+    return {
+        "tracking_error": float(np.sqrt(max(te_var, 0.0) * ann)),
+        "active_factor_vol": float(np.sqrt(max(active_factor_var, 0.0) * ann)),
+        "active_idio_vol": float(np.sqrt(max(active_idio_var, 0.0) * ann)),
+        "active_exposures": {f: float(v) for f, v in zip(model.factors, active)},
+    }