fix(ci): publish quant engine lite verification

README.md

@@ -60,7 +60,6 @@ from quant_engine.alpha_factors import alpha_001, alpha_005, ALPHA158_REGISTRY
 from quant_engine.execution import (
     ExecutionConfig, simulate_with_daily_data, compute_realized_pnl,
 )
-from quant_engine.backtest import run_weight_backtest
 from quant_engine.indicators import macd, bollinger, kdj
 from quant_engine.data_adapter import (
     long_to_wide, wide_to_long, rename_tushare_columns,
@@ -73,16 +72,6 @@ from quant_engine.data_adapter import (
 df = load_qtdb_daily(["000001.SZ"], "2024-01-01", with_adj=True)
 prices, volumes = prepare_execution_inputs(df)
 result = simulate_with_daily_data(prices, initial_cash=1_000_000.0)
-
-# 权重回测 → 稳定结果对象 → 绩效/基准分析
-backtest = run_weight_backtest(
-    weights=rebalance_weights,
-    stock_returns=daily_returns,
-    initial_capital=1_000_000.0,
-    benchmark_nav=benchmark_nav,
-)
-print(backtest.stats())
-print(backtest.benchmark_report())
 ```
 
 ## 与 research_results 的关系

src/quant_engine/backtest.py

@@ -13,28 +13,29 @@
 
 ```python
 from quant_engine.backtest import (
-    rebalance_periodic,           # 周期性再平衡
+    compute_nav_from_weights,    # 调仓表 → 净值
-    run_weight_backtest,          # 权重 → 统一结果对象
+    rebalance_table,              # 周期性再平衡
+    compare_to_benchmark,         # 策略 vs 基准
     weights_to_long_short,        # 多空组合
 )
 
-# 调仓表 → 净值、收益、绩效与基准报告
+# 1. 调仓表 → 净值
-rebalance_table = rebalance_periodic(target_weights, rebalance_dates, returns.index)
+nav = compute_nav_from_weights(
-result = run_weight_backtest(
     weights=rebalance_table,    # 每周/每月调仓
     stock_returns=returns,      # 个股日收益
     initial_capital=1.0,
-    benchmark_nav=benchmark_nav,
 )
-print(result.stats())
+
-print(result.benchmark_report())
+# 2. 跟基准比
+result = compare_to_benchmark(nav, benchmark_nav)
+print(result.summary())
 ```
 """
 
 from __future__ import annotations
 
+from pathlib import Path
 from collections.abc import Mapping, Sequence
-from dataclasses import dataclass
 
 import numpy as np
 import pandas as pd
@@ -45,26 +46,6 @@ from quant_engine.metrics import summary as metrics_summary
 logger = get_logger(__name__)
 
 
-@dataclass(frozen=True, slots=True, eq=False)
-class BacktestResult:
-    """一次权重回测的稳定结果快照。"""
-
-    nav: pd.Series
-    returns: pd.Series
-    weights: pd.DataFrame
-    benchmark_nav: pd.Series | None = None
-
-    def stats(self, rf: float = 0.0) -> Mapping[str, float]:
-        """返回标准绩效指标。"""
-        return metrics_summary(self.returns, rf)
-
-    def benchmark_report(self, rf: float = 0.0) -> pd.DataFrame:
-        """返回策略与基准的对比报告。"""
-        if self.benchmark_nav is None:
-            raise ValueError("benchmark_nav is required for benchmark comparison")
-        return compare_to_benchmark(self.nav, self.benchmark_nav, rf)
-
-
 # ── 调仓表 → 净值 ──────────────────────────────────────
 
 
@@ -132,29 +113,6 @@ def compute_returns_from_nav(nav: pd.Series) -> pd.Series:
     return nav.pct_change().fillna(0.0)
 
 
-def run_weight_backtest(
-    weights: pd.DataFrame,
-    stock_returns: pd.DataFrame,
-    initial_capital: float = 1.0,
-    tc_rate: float = 0.0,
-    benchmark_nav: pd.Series | None = None,
-) -> BacktestResult:
-    """执行权重回测并返回隔离于调用方输入的结果快照。"""
-    weights_snapshot = weights.copy(deep=True)
-    nav = compute_nav_from_weights(
-        weights=weights_snapshot,
-        stock_returns=stock_returns,
-        initial_capital=initial_capital,
-        tc_rate=tc_rate,
-    )
-    return BacktestResult(
-        nav=nav,
-        returns=compute_returns_from_nav(nav),
-        weights=weights_snapshot,
-        benchmark_nav=None if benchmark_nav is None else benchmark_nav.copy(deep=True),
-    )
-
-
 # ── 调仓工具 ──────────────────────────────────────
 
 
@@ -173,9 +131,6 @@ def rebalance_periodic(
     Returns:
         调仓表 DataFrame（all_dates × 股票代码）
     """
-    if all_dates.empty:
-        return pd.DataFrame(index=all_dates, columns=target_weights.index, dtype=float)
-
     table = pd.DataFrame(0.0, index=all_dates, columns=target_weights.index)
     for date in rebalance_dates:
         if date not in all_dates:
@@ -246,8 +201,6 @@ def compare_to_benchmark(
     """
     # 对齐 index
     common = strategy_nav.index.intersection(benchmark_nav.index)
-    if common.empty:
-        raise ValueError("strategy and benchmark must have overlapping dates")
     s = strategy_nav.loc[common]
     b = benchmark_nav.loc[common]
 

src/quant_engine/factor_library.py

@@ -312,8 +312,8 @@ def ols_regress(
     ss_tot = float(((y_arr - y_arr.mean()) ** 2).sum())
     r_sq = 1.0 - ss_res / ss_tot if ss_tot > 0 else np.nan
     sigma2 = ss_res / max(n - k, 1)
-    # 广义协方差矩阵 = sigma2 * (X'X)^+，伪逆兼容共线因子。
+    # 协方差矩阵 = sigma2 * (X'X)^-1
-    xtx_inv = np.linalg.pinv(x_arr.T @ x_arr) if sigma2 > 0 else np.full((k, k), np.nan)
+    xtx_inv = np.linalg.inv(x_arr.T @ x_arr) if sigma2 > 0 else np.full((k, k), np.nan)
     se = np.sqrt(np.diag(xtx_inv) * sigma2)
     t_vals = coef / se if sigma2 > 0 else np.full_like(coef, np.nan)
     if add_constant:
@@ -513,8 +513,6 @@ def apply_factor_direction(
     Returns:
         方向调整后的因子（同向 = 越大越好）
     """
-    if direction not in {"auto", "forward", "reverse"}:
-        raise ValueError(f"direction={direction!r} not supported (auto / forward / reverse)")
     if factor.empty:
         return factor.copy()
     if direction == "auto":
@@ -543,8 +541,6 @@ def cross_sectional_rank_with_direction(
     Returns:
         pd.Series（百分位排名 [0, 1]，越大越优）
     """
-    if direction not in {"auto", "forward", "reverse"}:
-        raise ValueError(f"direction={direction!r} not supported (auto / forward / reverse)")
     if df.empty or factor_col not in df.columns:
         return pd.Series(dtype=float)
     factor = df[factor_col]

src/quant_engine/metrics.py

@@ -71,8 +71,7 @@ def max_drawdown(r: pd.Series) -> float:
     if len(r) < 2:
         return 0.0
     nav = (1 + r).cumprod()
-    # 初始资金净值为 1；否则首个观测日的亏损会被误当成新的历史高点。
+    peak = nav.cummax()
-    peak = nav.cummax().clip(lower=1.0)
     drawdown = (nav - peak) / peak
     return float(drawdown.min())
 

src/quant_engine/risk.py

@@ -5,22 +5,9 @@
 
 from __future__ import annotations
 
-from typing import Any
-
 import numpy as np
 from numpy.typing import NDArray
-
+from typing import Any
-
-def _validate_inputs(weights: NDArray[Any], cov: NDArray[Any]) -> tuple[NDArray[Any], NDArray[Any]]:
-    """Normalize a portfolio vector and its covariance matrix."""
-    w = np.asarray(weights, dtype=float).ravel()
-    covariance = np.asarray(cov, dtype=float)
-    k = w.size
-    if k == 0:
-        raise ValueError("weights must contain at least one asset")
-    if covariance.shape != (k, k):
-        raise ValueError(f"cov shape {covariance.shape} does not match weights length {k}")
-    return w, covariance
 
 
 def risk_contribution(weights: NDArray[Any], cov: NDArray[Any]) -> NDArray[Any]:
@@ -38,8 +25,11 @@ def risk_contribution(weights: NDArray[Any], cov: NDArray[Any]) -> NDArray[Any]:
     Returns:
         RC: 风险贡献向量 (k,), Σ=1
     """
-    w, cov = _validate_inputs(weights, cov)
+    w = np.asarray(weights, dtype=float).ravel()
+    cov = np.asarray(cov, dtype=float)
     k = w.size
+    if cov.shape != (k, k):
+        raise ValueError(f"cov 形状 {cov.shape} 与 weights 长度 {k} 不匹配")
 
     port_var = float(w @ cov @ w)
     if port_var <= 0:
@@ -51,11 +41,13 @@ def risk_contribution(weights: NDArray[Any], cov: NDArray[Any]) -> NDArray[Any]:
 
 def marginal_risk_contribution(weights: NDArray[Any], cov: NDArray[Any]) -> NDArray[Any]:
     """边际风险贡献 (MRC_i): (Σw)_i。"""
-    w, cov = _validate_inputs(weights, cov)
+    w = np.asarray(weights, dtype=float).ravel()
+    cov = np.asarray(cov, dtype=float)
     return cov @ w  # type: ignore[no-any-return]
 
 
 def component_var(weights: NDArray[Any], cov: NDArray[Any]) -> NDArray[Any]:
     """成分方差: w_i · (Σw)_i; 与 RC 的关系 RC_i = CV_i / w'Σw。"""
-    w, cov = _validate_inputs(weights, cov)
+    w = np.asarray(weights, dtype=float).ravel()
+    cov = np.asarray(cov, dtype=float)
     return w * (cov @ w)  # type: ignore[no-any-return]

tests/test_backtest.py

@@ -1,209 +0,0 @@
-"""Backtest contract tests for weights, NAV, rebalancing, and benchmarks."""
-
-from __future__ import annotations
-
-import pandas as pd
-import pytest
-
-from quant_engine.backtest import (
-    BacktestResult,
-    compare_to_benchmark,
-    compute_nav_from_weights,
-    compute_returns_from_nav,
-    rebalance_periodic,
-    run_weight_backtest,
-    weights_to_long_short,
-)
-
-
-def test_compute_nav_from_weights_forward_fills_rebalance_weights() -> None:
-    dates = pd.date_range("2026-01-05", periods=3, freq="B")
-    weights = pd.DataFrame({"A": [0.5], "B": [0.5]}, index=dates[:1])
-    returns = pd.DataFrame({"A": [0.10, 0.00, -0.10], "B": [0.00, 0.10, 0.00]}, index=dates)
-
-    nav = compute_nav_from_weights(weights, returns, initial_capital=100.0)
-
-    expected = pd.Series([105.0, 110.25, 104.7375], index=dates)
-    pd.testing.assert_series_equal(nav, expected)
-
-
-def test_compute_nav_stays_in_cash_before_first_rebalance() -> None:
-    dates = pd.date_range("2026-01-05", periods=3, freq="B")
-    weights = pd.DataFrame({"A": [1.0]}, index=dates[1:2])
-    returns = pd.DataFrame({"A": [0.50, 0.10, 0.10]}, index=dates)
-
-    nav = compute_nav_from_weights(weights, returns)
-
-    pd.testing.assert_series_equal(nav, pd.Series([1.0, 1.1, 1.21], index=dates))
-
-
-def test_compute_nav_ignores_weight_columns_without_returns() -> None:
-    dates = pd.date_range("2026-01-05", periods=2, freq="B")
-    weights = pd.DataFrame({"A": [0.5], "MISSING": [0.5]}, index=dates[:1])
-    returns = pd.DataFrame({"A": [0.10, 0.10]}, index=dates)
-
-    nav = compute_nav_from_weights(weights, returns)
-
-    pd.testing.assert_series_equal(nav, pd.Series([1.05, 1.1025], index=dates))
-
-
-def test_compute_nav_charges_configured_turnover_cost() -> None:
-    dates = pd.date_range("2026-01-05", periods=2, freq="B")
-    weights = pd.DataFrame({"A": [1.0]}, index=dates[:1])
-    returns = pd.DataFrame({"A": [0.0, 0.0]}, index=dates)
-
-    nav = compute_nav_from_weights(weights, returns, tc_rate=0.01)
-
-    pd.testing.assert_series_equal(nav, pd.Series([0.995, 0.995], index=dates))
-
-
-def test_compute_returns_from_nav_preserves_index_and_sets_initial_zero() -> None:
-    nav = pd.Series([100.0, 110.0, 99.0], index=pd.date_range("2026-01-05", periods=3))
-
-    result = compute_returns_from_nav(nav)
-
-    pd.testing.assert_series_equal(result, pd.Series([0.0, 0.1, -0.1], index=nav.index))
-
-
-def test_rebalance_periodic_maps_weekend_to_previous_trading_day() -> None:
-    dates = pd.date_range("2026-01-05", periods=5, freq="B")
-    target = pd.Series({"A": 0.6, "B": 0.4})
-
-    result = rebalance_periodic(target, [pd.Timestamp("2026-01-10")], dates)
-
-    assert result.loc[pd.Timestamp("2026-01-08")].sum() == 0.0
-    pd.testing.assert_series_equal(
-        result.loc[pd.Timestamp("2026-01-09")], target, check_names=False
-    )
-
-
-def test_rebalance_periodic_accepts_empty_trading_calendar() -> None:
-    target = pd.Series({"A": 1.0})
-
-    result = rebalance_periodic(
-        target,
-        [pd.Timestamp("2026-01-05")],
-        pd.DatetimeIndex([]),
-    )
-
-    assert result.empty
-    assert result.columns.tolist() == ["A"]
-
-
-def test_weights_to_long_short_allocates_each_leg() -> None:
-    result = weights_to_long_short(["A", "B"], ["C"], long_weight=0.6, short_weight=0.4)
-
-    assert result["A"] == pytest.approx(0.3)
-    assert result["B"] == pytest.approx(0.3)
-    assert result["C"] == pytest.approx(-0.4)
-    assert result.sum() == pytest.approx(0.2)
-
-
-def test_weights_to_long_short_keeps_explicit_universe() -> None:
-    result = weights_to_long_short(["A"], [], all_tickers=["A", "B"])
-
-    pd.testing.assert_series_equal(result, pd.Series({"A": 0.5, "B": 0.0}))
-
-
-def test_compare_to_benchmark_returns_report_table() -> None:
-    dates = pd.date_range("2026-01-05", periods=4, freq="B")
-    strategy = pd.Series([1.0, 1.1, 1.0, 1.2], index=dates)
-    benchmark = pd.Series([1.0, 1.0, 1.05, 1.1], index=dates)
-
-    result = compare_to_benchmark(strategy, benchmark)
-
-    assert result.columns.tolist() == ["策略", "基准"]
-    assert result.loc["n_days", "策略"] == 4
-    assert result.loc["累计收益", "策略"] == pytest.approx(0.2)
-    assert result.loc["累计收益", "基准"] == pytest.approx(0.1)
-
-
-def test_compare_to_benchmark_rejects_non_overlapping_dates() -> None:
-    strategy = pd.Series([1.0], index=[pd.Timestamp("2026-01-05")])
-    benchmark = pd.Series([1.0], index=[pd.Timestamp("2026-02-05")])
-
-    with pytest.raises(ValueError, match="overlapping dates"):
-        compare_to_benchmark(strategy, benchmark)
-
-
-# ── 统一回测结果门面 ──────────────────────────────────────
-
-
-def test_run_weight_backtest_returns_nav_returns_and_input_snapshot() -> None:
-    dates = pd.date_range("2026-01-05", periods=3, freq="B")
-    weights = pd.DataFrame({"A": [1.0]}, index=dates[:1])
-    stock_returns = pd.DataFrame({"A": [0.10, -0.10, 0.20]}, index=dates)
-
-    result = run_weight_backtest(weights, stock_returns, initial_capital=100.0)
-
-    assert isinstance(result, BacktestResult)
-    pd.testing.assert_series_equal(
-        result.nav,
-        pd.Series([110.0, 99.0, 118.8], index=dates),
-    )
-    pd.testing.assert_series_equal(
-        result.returns,
-        pd.Series([0.0, -0.1, 0.2], index=dates),
-    )
-    pd.testing.assert_frame_equal(result.weights, weights)
-
-
-def test_backtest_result_stats_reuses_standard_metrics_contract() -> None:
-    dates = pd.date_range("2026-01-05", periods=3, freq="B")
-    result = run_weight_backtest(
-        pd.DataFrame({"A": [1.0]}, index=dates[:1]),
-        pd.DataFrame({"A": [0.10, -0.10, 0.20]}, index=dates),
-    )
-
-    stats = result.stats(rf=0.02)
-
-    assert stats["n_days"] == 3
-    assert stats["ann_return"] == pytest.approx(
-        (1.0 * 0.9 * 1.2) ** (252 / 3) - 1.0
-    )
-    assert "sharpe" in stats
-    assert stats["drawback"] == stats["max_drawdown"]
-
-
-def test_backtest_result_builds_benchmark_report() -> None:
-    dates = pd.date_range("2026-01-05", periods=3, freq="B")
-    benchmark = pd.Series([1.0, 1.05, 1.10], index=dates, name="benchmark")
-    result = run_weight_backtest(
-        pd.DataFrame({"A": [1.0]}, index=dates[:1]),
-        pd.DataFrame({"A": [0.10, -0.10, 0.20]}, index=dates),
-        benchmark_nav=benchmark,
-    )
-
-    report = result.benchmark_report()
-
-    assert report.columns.tolist() == ["策略", "基准"]
-    assert report.loc["累计收益", "基准"] == pytest.approx(0.10)
-
-
-def test_backtest_result_requires_benchmark_for_comparison() -> None:
-    dates = pd.date_range("2026-01-05", periods=2, freq="B")
-    result = run_weight_backtest(
-        pd.DataFrame({"A": [1.0]}, index=dates[:1]),
-        pd.DataFrame({"A": [0.0, 0.0]}, index=dates),
-    )
-
-    with pytest.raises(ValueError, match="benchmark_nav"):
-        result.benchmark_report()
-
-
-def test_backtest_result_isolated_from_mutated_caller_inputs() -> None:
-    dates = pd.date_range("2026-01-05", periods=2, freq="B")
-    weights = pd.DataFrame({"A": [1.0]}, index=dates[:1])
-    benchmark = pd.Series([1.0, 1.1], index=dates)
-    result = run_weight_backtest(
-        weights,
-        pd.DataFrame({"A": [0.0, 0.0]}, index=dates),
-        benchmark_nav=benchmark,
-    )
-
-    weights.iloc[0, 0] = 0.0
-    benchmark.iloc[1] = 99.0
-
-    assert result.weights.iloc[0, 0] == 1.0
-    assert result.benchmark_nav is not None
-    assert result.benchmark_nav.iloc[1] == 1.1

tests/test_factor_library.py

@@ -1,173 +0,0 @@
-"""Contracts for reusable factor diagnostics and transformations."""
-
-from __future__ import annotations
-
-import numpy as np
-import pandas as pd
-import pytest
-
-from quant_engine.factor_library import (
-    annualized_sharpe,
-    apply_factor_direction,
-    cross_sectional_momentum,
-    cross_sectional_pct_rank,
-    cross_sectional_rank_with_direction,
-    ic_summary,
-    jb_test,
-    kurtosis,
-    ols_regress,
-    rolling_annual_vol,
-    rolling_zscore,
-    skewness,
-    spearman_ic,
-    time_series_momentum,
-    turnover,
-    winsorize,
-)
-
-
-def test_turnover_supports_one_way_and_round_trip_conventions() -> None:
-    weights = pd.DataFrame({"A": [1.0, 0.0], "B": [0.0, 1.0]})
-
-    pd.testing.assert_series_equal(turnover(weights), pd.Series([1.0], index=[1]))
-    pd.testing.assert_series_equal(
-        turnover(weights, divide_by_two=False), pd.Series([2.0], index=[1])
-    )
-    assert turnover(weights.iloc[:1]).empty
-
-
-def test_ic_functions_measure_monotonic_relationship() -> None:
-    factor = pd.Series([1.0, 2.0, 3.0, 4.0])
-    forward = pd.Series([10.0, 20.0, 30.0, 40.0])
-
-    assert spearman_ic(factor, forward) == pytest.approx(1.0)
-    result = ic_summary(factor, forward, periods=(1,), method="pearson")
-    assert result.loc[1, "ic_mean"] == pytest.approx(1.0)
-    assert result.loc[1, "n"] == 4
-
-
-def test_ic_summary_rejects_unknown_method() -> None:
-    with pytest.raises(ValueError, match="not supported"):
-        ic_summary(pd.Series([1, 2, 3]), pd.Series([1, 2, 3]), method="kendall")
-
-
-def test_winsorize_clips_tails_and_preserves_nan() -> None:
-    values = pd.Series([0.0, 1.0, 2.0, 100.0, np.nan])
-
-    result = winsorize(values, lower=0.25, upper=0.75)
-
-    assert result.iloc[0] == pytest.approx(0.75)
-    assert result.iloc[3] == pytest.approx(26.5)
-    assert pd.isna(result.iloc[4])
-
-
-def test_distribution_diagnostics_handle_short_samples() -> None:
-    assert np.isnan(skewness(pd.Series([1.0, 2.0])))
-    assert np.isnan(kurtosis(pd.Series([1.0, 2.0, 3.0])))
-    jb, p_value = jb_test(pd.Series(range(7), dtype=float))
-    assert np.isnan(jb)
-    assert np.isnan(p_value)
-
-
-def test_distribution_diagnostics_return_finite_values() -> None:
-    values = pd.Series([-2.0, -1.0, -0.5, 0.0, 0.25, 0.75, 1.0, 3.0])
-
-    assert np.isfinite(skewness(values))
-    assert np.isfinite(kurtosis(values))
-    jb, p_value = jb_test(values)
-    assert jb >= 0
-    assert 0 <= p_value <= 1
-
-
-def test_ols_recovers_linear_coefficients_and_residual_index() -> None:
-    index = pd.date_range("2026-01-01", periods=8)
-    factor = pd.Series(np.arange(8, dtype=float), index=index, name="factor")
-    target = 1.5 + 2.0 * factor
-
-    result = ols_regress(target, factor)
-
-    assert result.alpha == pytest.approx(1.5)
-    assert result.beta["factor"] == pytest.approx(2.0)
-    assert result.r_squared == pytest.approx(1.0)
-    assert result.n == 8
-    assert result.resid.index.equals(index)
-
-
-def test_ols_handles_collinear_factors_without_crashing() -> None:
-    x = pd.DataFrame({"a": np.arange(8, dtype=float), "b": np.arange(8, dtype=float)})
-    y = pd.Series(1.0 + x["a"])
-
-    result = ols_regress(y, x)
-
-    assert result.n == 8
-    assert np.isfinite(result.beta).all()
-    np.testing.assert_allclose(result.resid, 0.0, atol=1e-12)
-
-
-def test_ols_short_sample_returns_empty_estimate() -> None:
-    result = ols_regress(pd.Series([1.0, 2.0]), pd.Series([1.0, 2.0], name="x"))
-
-    assert np.isnan(result.alpha)
-    assert result.beta.empty
-    assert result.n == 2
-
-
-def test_momentum_and_rolling_transforms_match_manual_values() -> None:
-    prices = pd.DataFrame({"A": [100.0, 110.0, 121.0, 133.1]})
-    momentum = cross_sectional_momentum(prices, lookback=2, skip=0)
-    assert momentum.iloc[2, 0] == pytest.approx(0.21)
-
-    returns = pd.Series([0.1, 0.1, -0.5, -0.5])
-    pd.testing.assert_series_equal(
-        time_series_momentum(returns, lookback=2),
-        pd.Series([0, 1, -1, -1]),
-    )
-
-    values = pd.Series([1.0, 2.0, 3.0])
-    zscore = rolling_zscore(values, window=3)
-    assert zscore.iloc[-1] == pytest.approx(1.0)
-    annual_vol = rolling_annual_vol(returns, window=2, min_periods=2, trading_days=4)
-    assert annual_vol.iloc[1] == pytest.approx(0.0)
-
-
-def test_rank_helpers_support_global_and_grouped_ranking() -> None:
-    frame = pd.DataFrame(
-        {"factor": [3.0, 1.0, 2.0, 4.0], "industry": ["x", "x", "y", "y"]}
-    )
-
-    global_rank = cross_sectional_pct_rank(frame, "factor", ascending=True)
-    grouped_rank = cross_sectional_pct_rank(
-        frame, "factor", group_col="industry", ascending=True
-    )
-
-    assert global_rank.tolist() == [0.75, 0.25, 0.5, 1.0]
-    assert grouped_rank.tolist() == [1.0, 0.5, 0.5, 1.0]
-    assert cross_sectional_pct_rank(frame, "missing").empty
-
-
-def test_factor_direction_and_directional_rank() -> None:
-    pe = pd.Series([10.0, 20.0], name="pe_ttm")
-    pd.testing.assert_series_equal(apply_factor_direction(pe), -pe)
-
-    frame = pd.DataFrame({"pe_ttm": [10.0, 20.0], "roe": [0.1, 0.2]})
-    assert cross_sectional_rank_with_direction(frame, "pe_ttm").tolist() == [1.0, 0.5]
-    assert cross_sectional_rank_with_direction(frame, "roe").tolist() == [0.5, 1.0]
-
-
-@pytest.mark.parametrize("direction", ["sideways", "", "REVERSE"])
-def test_factor_direction_rejects_unknown_values(direction: str) -> None:
-    factor = pd.Series([1.0, 2.0], name="roe")
-
-    with pytest.raises(ValueError, match="direction"):
-        apply_factor_direction(factor, direction=direction)
-    with pytest.raises(ValueError, match="direction"):
-        cross_sectional_rank_with_direction(
-            pd.DataFrame({"roe": factor}), "roe", direction=direction
-        )
-
-
-def test_annualized_sharpe_handles_empty_and_nonzero_returns() -> None:
-    assert annualized_sharpe(pd.Series(dtype=float)) == 0.0
-    returns = pd.Series([0.01, -0.01, 0.02, 0.0])
-    expected = returns.mean() * 252 / (returns.std() * np.sqrt(252))
-    assert annualized_sharpe(returns) == pytest.approx(expected)

tests/test_metrics.py

@@ -1,93 +0,0 @@
-"""Mathematical contracts for the standard performance metrics."""
-
-from __future__ import annotations
-
-import numpy as np
-import pandas as pd
-import pytest
-
-from quant_engine.metrics import (
-    TRADING_DAYS_PER_YEAR,
-    annualized_return,
-    annualized_volatility,
-    calmar_ratio,
-    max_drawdown,
-    sharpe_ratio,
-    summary,
-    win_rate,
-)
-
-
-def test_annualized_return_uses_compounded_simple_returns() -> None:
-    returns = pd.Series([0.10, -0.10])
-    expected = 0.99 ** (TRADING_DAYS_PER_YEAR / 2) - 1.0
-
-    assert annualized_return(returns) == pytest.approx(expected)
-
-
-def test_annualized_volatility_uses_sample_standard_deviation() -> None:
-    returns = pd.Series([0.01, 0.03, 0.02])
-
-    assert annualized_volatility(returns) == pytest.approx(
-        returns.std() * np.sqrt(TRADING_DAYS_PER_YEAR)
-    )
-
-
-def test_sharpe_ratio_subtracts_annual_risk_free_rate() -> None:
-    returns = pd.Series([0.01, -0.005, 0.02, 0.0])
-
-    result = sharpe_ratio(returns, rf=0.02)
-
-    assert result == pytest.approx(
-        (annualized_return(returns) - 0.02) / annualized_volatility(returns)
-    )
-
-
-def test_zero_volatility_metrics_return_zero() -> None:
-    returns = pd.Series([0.0, 0.0, 0.0])
-
-    assert sharpe_ratio(returns) == 0.0
-    assert calmar_ratio(returns) == 0.0
-
-
-def test_max_drawdown_includes_loss_from_initial_capital() -> None:
-    returns = pd.Series([-0.20, 0.0])
-
-    assert max_drawdown(returns) == pytest.approx(-0.20)
-
-
-def test_max_drawdown_tracks_peak_to_trough_loss() -> None:
-    returns = pd.Series([0.10, -0.20, 0.05])
-
-    assert max_drawdown(returns) == pytest.approx(-0.20)
-
-
-def test_metrics_clean_nan_and_infinite_values() -> None:
-    returns = pd.Series([0.10, np.nan, np.inf, -0.05, -np.inf])
-
-    assert win_rate(returns) == 0.5
-    assert summary(returns)["n_days"] == 2
-
-
-def test_summary_aliases_match_canonical_fields() -> None:
-    result = summary(pd.Series([0.01, -0.02, 0.03]))
-
-    assert result["annual_yield"] == result["ann_return"]
-    assert result["annual_sd"] == result["ann_volatility"]
-    assert result["drawback"] == result["max_drawdown"]
-
-
-@pytest.mark.parametrize(
-    "metric",
-    [annualized_return, annualized_volatility, sharpe_ratio, max_drawdown, calmar_ratio, win_rate],
-)
-def test_metrics_reject_non_series_input(metric) -> None:
-    with pytest.raises(TypeError, match=r"expected pd\.Series"):
-        metric([0.01, 0.02])
-
-
-def test_short_and_empty_series_return_zero() -> None:
-    assert annualized_return(pd.Series(dtype=float)) == 0.0
-    assert annualized_volatility(pd.Series([0.01])) == 0.0
-    assert max_drawdown(pd.Series([0.01])) == 0.0
-    assert win_rate(pd.Series(dtype=float)) == 0.0

tests/test_risk.py

@@ -1,54 +0,0 @@
-"""Risk contribution contracts and validation tests."""
-
-from __future__ import annotations
-
-import numpy as np
-import pytest
-
-from quant_engine.risk import component_var, marginal_risk_contribution, risk_contribution
-
-
-def test_risk_contribution_sums_to_one_for_positive_portfolio_variance() -> None:
-    weights = np.array([0.5, 0.5])
-    covariance = np.diag([1.0, 4.0])
-
-    result = risk_contribution(weights, covariance)
-
-    np.testing.assert_allclose(result, [0.2, 0.8])
-    assert result.sum() == pytest.approx(1.0)
-
-
-def test_zero_variance_portfolio_falls_back_to_equal_contribution() -> None:
-    result = risk_contribution(np.array([0.2, 0.3, 0.5]), np.zeros((3, 3)))
-
-    np.testing.assert_allclose(result, np.full(3, 1 / 3))
-
-
-def test_marginal_and_component_risk_follow_matrix_identities() -> None:
-    weights = np.array([0.25, 0.75])
-    covariance = np.array([[0.04, 0.01], [0.01, 0.09]])
-
-    marginal = marginal_risk_contribution(weights, covariance)
-    component = component_var(weights, covariance)
-
-    np.testing.assert_allclose(marginal, covariance @ weights)
-    np.testing.assert_allclose(component, weights * marginal)
-    assert component.sum() == pytest.approx(weights @ covariance @ weights)
-
-
-@pytest.mark.parametrize(
-    "function",
-    [risk_contribution, marginal_risk_contribution, component_var],
-)
-def test_risk_functions_reject_covariance_shape_mismatch(function) -> None:
-    with pytest.raises(ValueError, match="does not match weights length"):
-        function(np.array([0.5, 0.5]), np.eye(3))
-
-
-@pytest.mark.parametrize(
-    "function",
-    [risk_contribution, marginal_risk_contribution, component_var],
-)
-def test_risk_functions_reject_empty_portfolio(function) -> None:
-    with pytest.raises(ValueError, match="at least one asset"):
-        function(np.array([]), np.empty((0, 0)))