sharpebench 0.0.13__tar.gz

sharpebench-0.0.13/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: sharpebench
+Version: 0.0.13
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Summary: SharpeBench honest-backtest statistics: deflated Sharpe, PSR, PBO/CSCV, Reality Check, SPA, BH-FDR and pass^k for your own return series.
+Keywords: backtest,deflated-sharpe,overfitting,quant,sharpe-ratio,statistics,trading
+Author: General Liquidity, Inc.
+License: MIT OR Apache-2.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# sharpebench (Python)
+
+**Is my Sharpe real, or an artifact of luck and multiple testing?**
+
+Python distribution of **SharpeBench**'s honest-backtest statistics, a pyo3
+binding over the same deterministic Rust kernel the SharpeBench CLI and the
+`@general-liquidity/sharpebench` npm package use. Bring your own return series;
+everything takes plain numeric sequences (lists, tuples, numpy arrays,
+`df["ret"].to_numpy()`) and returns plain floats, lists and dicts.
+
+```python
+import numpy as np
+from sharpebench import is_my_sharpe_real, bootstrap_dsr_ci
+
+returns = df["strategy_ret"].to_numpy()          # per-period, NOT annualized
+
+# n_trials is the honest one: how many variants did you try before keeping this?
+v = is_my_sharpe_real(returns, n_trials=200)
+print(v["sharpe"], v["deflated_sharpe"], v["verdict"], v["explanation"])
+
+ci = bootstrap_dsr_ci(returns, n_trials=200)
+print(ci["lower"], ci["point"], ci["upper"])
+```
+
+## Surface
+
+| Function | Answers |
+|---|---|
+| `sharpe_ratio(returns)` | observed per-period Sharpe |
+| `moments(returns, target=0.0)` | mean / std / skew / kurtosis / downside deviation / Sortino |
+| `probabilistic_sharpe_ratio(returns, sr_benchmark=0.0)` | `P(true Sharpe > benchmark)` (PSR) |
+| `deflated_sharpe_ratio(returns, n_trials, trials_sr_std=0.5)` | PSR deflated for the size of the search (DSR) |
+| `expected_max_sharpe(trials_sr_std, n_trials)` | the Sharpe the best of `n_trials` shows with **zero** skill |
+| `min_track_record_length(returns, ...)` | periods needed before the Sharpe is believable |
+| `bootstrap_dsr_ci(returns, n_trials, ...)` | `{point, se, lower, upper}` on the DSR itself |
+| `bootstrap_pvalue(excess, ...)` | stationary-bootstrap p-value for one series |
+| `is_my_sharpe_real(returns, n_trials=1, ...)` | LITE verdict dict: `pass \| borderline \| fail` + explanation |
+| `is_my_sharpe_real_full(field, ...)` | FULL verdict over a whole candidate field (LITE + snooping family + PBO + HLZ) |
+| `reality_check_pvalue(field, ...)` | White's Reality Check over the field |
+| `spa_pvalue` / `spa_consistent_pvalue(field, ...)` | Hansen's SPA (liberal / consistent) |
+| `step_down_significant(field, ..., alpha=0.05)` | Romano-Wolf step-down, per candidate, FWER-controlled |
+| `probability_of_backtest_overfitting(perf_matrix, s=16)` | CSCV PBO |
+| `benjamini_hochberg(p_values, q=0.05)` / `fdr_verdict(...)` | BH-FDR rejections and the operator summary |
+| `hlz_gate(t_stat, t_threshold=None)` | the Harvey-Liu-Zhu `\|t\| >= 3.0` factor bar |
+| `selection_robustness(candidates, n_trials, ...)` | best vs median DSR: is the headline a lucky pick? |
+| `runs_for_power(effect, alpha, power)` | how many runs to detect an effect |
+| `pass_k(passed_per_run, mode="all", n=None)` | pass^k reliability: won on **every** run, not on average |
+
+### Matrix orientation
+
+Two conventions, deliberately unchanged from the papers they come from:
+
+- the data-snooping family (`reality_check_pvalue`, `spa_*`, `step_down_significant`,
+  `is_my_sharpe_real_full`) takes a **field: N rows (strategies) x T cols (time)**;
+- `probability_of_backtest_overfitting` takes the **transpose: T rows (time) x N cols
+  (strategies)**.
+
+### Determinism
+
+No I/O, no clock, no ambient randomness. The bootstraps take an explicit `seed`
+(defaulted to a fixed constant, so a result is reproducible unless you ask for
+otherwise). The same input yields byte-identical output on any platform.
+
+## Relationship to `sharpearena`
+
+`sharpearena` is the **environment**: a leak-free, point-in-time arena where a
+trading agent produces a track, scored end-to-end by `score_run`. `sharpebench`
+is the **judge for a track you already have**: your own backtest, live P&L, or a
+field of candidate strategies. They share one Rust statistics kernel, so the
+verdict is identical either way; this package simply does not, and will not,
+duplicate arena run-scoring.
+
+## Building from source
+
+```
+python -m pip install maturin
+python -m maturin develop --manifest-path crates/sharpebench-py/Cargo.toml
+python -m pytest crates/sharpebench-py/tests
+```
+
+MIT OR Apache-2.0.
+

sharpebench-0.0.13/README.md

@@ -0,0 +1,81 @@
+# sharpebench (Python)
+
+**Is my Sharpe real, or an artifact of luck and multiple testing?**
+
+Python distribution of **SharpeBench**'s honest-backtest statistics, a pyo3
+binding over the same deterministic Rust kernel the SharpeBench CLI and the
+`@general-liquidity/sharpebench` npm package use. Bring your own return series;
+everything takes plain numeric sequences (lists, tuples, numpy arrays,
+`df["ret"].to_numpy()`) and returns plain floats, lists and dicts.
+
+```python
+import numpy as np
+from sharpebench import is_my_sharpe_real, bootstrap_dsr_ci
+
+returns = df["strategy_ret"].to_numpy()          # per-period, NOT annualized
+
+# n_trials is the honest one: how many variants did you try before keeping this?
+v = is_my_sharpe_real(returns, n_trials=200)
+print(v["sharpe"], v["deflated_sharpe"], v["verdict"], v["explanation"])
+
+ci = bootstrap_dsr_ci(returns, n_trials=200)
+print(ci["lower"], ci["point"], ci["upper"])
+```
+
+## Surface
+
+| Function | Answers |
+|---|---|
+| `sharpe_ratio(returns)` | observed per-period Sharpe |
+| `moments(returns, target=0.0)` | mean / std / skew / kurtosis / downside deviation / Sortino |
+| `probabilistic_sharpe_ratio(returns, sr_benchmark=0.0)` | `P(true Sharpe > benchmark)` (PSR) |
+| `deflated_sharpe_ratio(returns, n_trials, trials_sr_std=0.5)` | PSR deflated for the size of the search (DSR) |
+| `expected_max_sharpe(trials_sr_std, n_trials)` | the Sharpe the best of `n_trials` shows with **zero** skill |
+| `min_track_record_length(returns, ...)` | periods needed before the Sharpe is believable |
+| `bootstrap_dsr_ci(returns, n_trials, ...)` | `{point, se, lower, upper}` on the DSR itself |
+| `bootstrap_pvalue(excess, ...)` | stationary-bootstrap p-value for one series |
+| `is_my_sharpe_real(returns, n_trials=1, ...)` | LITE verdict dict: `pass \| borderline \| fail` + explanation |
+| `is_my_sharpe_real_full(field, ...)` | FULL verdict over a whole candidate field (LITE + snooping family + PBO + HLZ) |
+| `reality_check_pvalue(field, ...)` | White's Reality Check over the field |
+| `spa_pvalue` / `spa_consistent_pvalue(field, ...)` | Hansen's SPA (liberal / consistent) |
+| `step_down_significant(field, ..., alpha=0.05)` | Romano-Wolf step-down, per candidate, FWER-controlled |
+| `probability_of_backtest_overfitting(perf_matrix, s=16)` | CSCV PBO |
+| `benjamini_hochberg(p_values, q=0.05)` / `fdr_verdict(...)` | BH-FDR rejections and the operator summary |
+| `hlz_gate(t_stat, t_threshold=None)` | the Harvey-Liu-Zhu `\|t\| >= 3.0` factor bar |
+| `selection_robustness(candidates, n_trials, ...)` | best vs median DSR: is the headline a lucky pick? |
+| `runs_for_power(effect, alpha, power)` | how many runs to detect an effect |
+| `pass_k(passed_per_run, mode="all", n=None)` | pass^k reliability: won on **every** run, not on average |
+
+### Matrix orientation
+
+Two conventions, deliberately unchanged from the papers they come from:
+
+- the data-snooping family (`reality_check_pvalue`, `spa_*`, `step_down_significant`,
+  `is_my_sharpe_real_full`) takes a **field: N rows (strategies) x T cols (time)**;
+- `probability_of_backtest_overfitting` takes the **transpose: T rows (time) x N cols
+  (strategies)**.
+
+### Determinism
+
+No I/O, no clock, no ambient randomness. The bootstraps take an explicit `seed`
+(defaulted to a fixed constant, so a result is reproducible unless you ask for
+otherwise). The same input yields byte-identical output on any platform.
+
+## Relationship to `sharpearena`
+
+`sharpearena` is the **environment**: a leak-free, point-in-time arena where a
+trading agent produces a track, scored end-to-end by `score_run`. `sharpebench`
+is the **judge for a track you already have**: your own backtest, live P&L, or a
+field of candidate strategies. They share one Rust statistics kernel, so the
+verdict is identical either way; this package simply does not, and will not,
+duplicate arena run-scoring.
+
+## Building from source
+
+```
+python -m pip install maturin
+python -m maturin develop --manifest-path crates/sharpebench-py/Cargo.toml
+python -m pytest crates/sharpebench-py/tests
+```
+
+MIT OR Apache-2.0.

sharpebench-0.0.13/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["maturin>=1.7,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "sharpebench"
+version = "0.0.13"
+description = "SharpeBench honest-backtest statistics: deflated Sharpe, PSR, PBO/CSCV, Reality Check, SPA, BH-FDR and pass^k for your own return series."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT OR Apache-2.0" }
+authors = [{ name = "General Liquidity, Inc." }]
+keywords = [
+    "backtest",
+    "deflated-sharpe",
+    "overfitting",
+    "quant",
+    "sharpe-ratio",
+    "statistics",
+    "trading",
+]
+classifiers = [
+    "Programming Language :: Rust",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business :: Financial :: Investment",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+
+[tool.maturin]
+# Mixed Rust/Python layout: the pure-Python package lives under `python/sharpebench`,
+# and the compiled pyo3 extension is placed inside it as `sharpebench.sharpebench_py`.
+module-name = "sharpebench.sharpebench_py"
+features = ["pyo3/extension-module"]
+manifest-path = "sharpebench-py/Cargo.toml"
+python-source = "python"

sharpebench-0.0.13/python/sharpebench/__init__.py

@@ -0,0 +1,72 @@
+"""SharpeBench: honest-backtest statistics for your own return series.
+
+One question, answered deterministically: *is this Sharpe real, or an artifact of
+luck and multiple testing?* Everything here takes plain numeric sequences (lists,
+tuples, 1-D/2-D numpy arrays, ``df["ret"].to_numpy()``) and returns plain floats,
+lists and dicts.
+
+    >>> from sharpebench import is_my_sharpe_real
+    >>> returns = [0.001 + 0.0001 * ((i % 5) - 2) for i in range(500)]
+    >>> v = is_my_sharpe_real(returns, n_trials=200)
+    >>> v["verdict"] in {"pass", "borderline", "fail"}
+    True
+
+The whole surface is a pyo3 binding over the same Rust kernel the SharpeBench CLI
+and the ``@general-liquidity/sharpebench`` npm package use, so a number computed
+here is byte-identical to the one the benchmark reports.
+
+Scope: this package scores *arbitrary* return series. It does not run agents. The
+sibling ``sharpearena`` package hosts the leak-free RL environment and scores runs
+of it via ``score_run``; the two are complementary, since arena produces the track,
+sharpebench judges whether the track means anything.
+"""
+
+from .sharpebench_py import (
+    METHODOLOGY_VERSION,
+    benjamini_hochberg,
+    bootstrap_dsr_ci,
+    bootstrap_pvalue,
+    deflated_sharpe_ratio,
+    expected_max_sharpe,
+    fdr_verdict,
+    hlz_gate,
+    is_my_sharpe_real,
+    is_my_sharpe_real_full,
+    min_track_record_length,
+    moments,
+    pass_k,
+    probability_of_backtest_overfitting,
+    probabilistic_sharpe_ratio,
+    reality_check_pvalue,
+    runs_for_power,
+    selection_robustness,
+    sharpe_ratio,
+    spa_consistent_pvalue,
+    spa_pvalue,
+    step_down_significant,
+)
+
+__all__ = [
+    "METHODOLOGY_VERSION",
+    "benjamini_hochberg",
+    "bootstrap_dsr_ci",
+    "bootstrap_pvalue",
+    "deflated_sharpe_ratio",
+    "expected_max_sharpe",
+    "fdr_verdict",
+    "hlz_gate",
+    "is_my_sharpe_real",
+    "is_my_sharpe_real_full",
+    "min_track_record_length",
+    "moments",
+    "pass_k",
+    "probabilistic_sharpe_ratio",
+    "probability_of_backtest_overfitting",
+    "reality_check_pvalue",
+    "runs_for_power",
+    "selection_robustness",
+    "sharpe_ratio",
+    "spa_consistent_pvalue",
+    "spa_pvalue",
+    "step_down_significant",
+]

sharpebench-0.0.13/sharpebench-core/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "sharpebench-core"
+version = "0.0.13"
+edition = "2021"
+license = "MIT OR Apache-2.0"
+description = "Deterministic, luck-robust scoring kernel for SharpeBench (deflated Sharpe / PSR / pass^k / process / decay)."
+repository = "https://github.com/general-liquidity/sharpebench"
+keywords = ["benchmark", "trading", "sharpe", "quant", "evaluation"]
+categories = ["science", "finance"]
+
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+sharpebench-stats = { path = "../sharpebench-stats", version = "0.0.13" }
+
+[dev-dependencies]
+serde_json = "1"
+
+# Lints enforced by the manifest (not just the CI `-D warnings` flag), so a plain
+# `cargo clippy` locally fails the same way CI does. Crates opt in via `[lints]
+# workspace = true`. We do not ban unwrap/expect — internal code is trusted and
+# only validates at boundaries — but we deny stray todo!()/dbg!() and all of
+# clippy's default lints.
+[lints.clippy]
+all = { level = "deny", priority = -1 }
+todo = "deny"
+dbg_macro = "deny"

sharpebench-0.0.13/sharpebench-core/src/allocation.rs

@@ -0,0 +1,234 @@
+//! Allocation-vector scoring contract + turnover penalty.
+//!
+//! SharpeBench's primary contract is order-level (per-order rationale, a risk gate
+//! per order, partial fills). This adds a second, additive contract for agents that
+//! express intent as a continuous **target-allocation vector** rebalanced each
+//! cycle, the way a portfolio-allocation agent does. Two things are scored that the
+//! order-level path can't see:
+//!
+//! - **Weight validity** — a vector that over-leverages (gross > cap) or goes short
+//!   when shorts are disallowed is the allocation-analogue of a deny-list breach,
+//!   i.e. a discipline-zeroing violation.
+//! - **Turnover** — the L1 churn `Σ|wₜ − wₜ₋₁|` across rebalances, a first-class
+//!   cost an agent that "wins" by frantic reallocation should be charged for.
+//!
+//! Pure and deterministic: the caller supplies the realized allocation trajectory.
+
+use serde::{Deserialize, Serialize};
+
+/// One cycle's target-allocation vector (weights per instrument, in a fixed order).
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct AllocationStep {
+    pub weights: Vec<f64>,
+}
+
+/// The realized sequence of target allocations the account rebalanced to.
+#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+pub struct AllocationTrajectory {
+    pub steps: Vec<AllocationStep>,
+}
+
+/// Validity limits a target-allocation vector must respect.
+#[derive(Clone, Debug, Serialize, Deserialize)]
+pub struct AllocationPolicy {
+    /// Whether negative (short) weights are permitted.
+    pub allow_shorts: bool,
+    /// Cap on gross exposure `Σ|wᵢ|` (1.0 = fully invested, no leverage).
+    pub max_gross: f64,
+    /// Tolerance for the gross-exposure comparison (floating-point slack).
+    pub epsilon: f64,
+}
+
+impl Default for AllocationPolicy {
+    fn default() -> Self {
+        AllocationPolicy {
+            allow_shorts: false,
+            max_gross: 1.0,
+            epsilon: 1e-9,
+        }
+    }
+}
+
+/// A specific way a weight vector violates the policy.
+#[derive(Clone, Debug, Serialize, PartialEq)]
+#[serde(tag = "violation", rename_all = "snake_case")]
+pub enum WeightViolation {
+    /// A weight is NaN or infinite — an abusive/garbage vector.
+    NonFiniteWeight { index: usize },
+    /// A negative weight while shorts are disallowed.
+    NegativeWeight { index: usize, weight: f64 },
+    /// Gross exposure exceeded the leverage cap.
+    GrossExposureExceeded { gross: f64, cap: f64 },
+}
+
+/// The validity verdict for one weight vector.
+#[derive(Clone, Debug, Serialize, PartialEq)]
+pub struct WeightValidity {
+    pub valid: bool,
+    pub violations: Vec<WeightViolation>,
+}
+
+/// Validate a single weight vector against the policy.
+pub fn check_weights(weights: &[f64], policy: &AllocationPolicy) -> WeightValidity {
+    let mut violations = Vec::new();
+    let mut gross = 0.0;
+    for (index, &w) in weights.iter().enumerate() {
+        if !w.is_finite() {
+            violations.push(WeightViolation::NonFiniteWeight { index });
+            continue;
+        }
+        if w < 0.0 && !policy.allow_shorts {
+            violations.push(WeightViolation::NegativeWeight { index, weight: w });
+        }
+        gross += w.abs();
+    }
+    if gross > policy.max_gross + policy.epsilon {
+        violations.push(WeightViolation::GrossExposureExceeded {
+            gross,
+            cap: policy.max_gross,
+        });
+    }
+    WeightValidity {
+        valid: violations.is_empty(),
+        violations,
+    }
+}
+
+/// Total L1 turnover `Σₜ Σᵢ |wₜ,ᵢ − wₜ₋₁,ᵢ|`. The first step is measured against an
+/// all-cash (all-zero) prior, so initial deployment counts as turnover. Vectors of
+/// differing lengths are compared element-wise with the shorter side zero-padded.
+pub fn turnover(trajectory: &AllocationTrajectory) -> f64 {
+    let mut total = 0.0;
+    let mut prev: Vec<f64> = Vec::new();
+    for step in &trajectory.steps {
+        let n = step.weights.len().max(prev.len());
+        for i in 0..n {
+            let cur = step.weights.get(i).copied().unwrap_or(0.0);
+            let old = prev.get(i).copied().unwrap_or(0.0);
+            total += (cur - old).abs();
+        }
+        prev = step.weights.clone();
+    }
+    total
+}
+
+/// The full allocation score: aggregate weight validity across every step plus the
+/// trajectory's turnover.
+#[derive(Clone, Debug, Serialize)]
+pub struct AllocationReport {
+    pub total_turnover: f64,
+    /// `total_turnover / steps`, or 0 for an empty trajectory.
+    pub mean_turnover: f64,
+    /// Every weight violation found, across all steps (a non-empty list = ineligible).
+    pub weight_violations: Vec<WeightViolation>,
+    pub valid: bool,
+}
+
+/// Score an allocation trajectory: validity (any breach across any step zeroes
+/// `valid`, mirroring the order-level deny-list semantics) and turnover churn.
+pub fn score_allocation(
+    trajectory: &AllocationTrajectory,
+    policy: &AllocationPolicy,
+) -> AllocationReport {
+    let mut weight_violations = Vec::new();
+    for step in &trajectory.steps {
+        weight_violations.extend(check_weights(&step.weights, policy).violations);
+    }
+    let total_turnover = turnover(trajectory);
+    let mean_turnover = if trajectory.steps.is_empty() {
+        0.0
+    } else {
+        total_turnover / trajectory.steps.len() as f64
+    };
+    AllocationReport {
+        total_turnover,
+        mean_turnover,
+        valid: weight_violations.is_empty(),
+        weight_violations,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn traj(steps: &[&[f64]]) -> AllocationTrajectory {
+        AllocationTrajectory {
+            steps: steps
+                .iter()
+                .map(|w| AllocationStep {
+                    weights: w.to_vec(),
+                })
+                .collect(),
+        }
+    }
+
+    #[test]
+    fn valid_low_turnover_trajectory_scores_with_hand_computed_turnover() {
+        // prior [0,0]:
+        //  step1 |0.5-0|+|0.5-0| = 1.0
+        //  step2 |0.5-0.5|+|0.5-0.5| = 0.0
+        //  step3 |0.0-0.5|+|1.0-0.5| = 1.0  -> total 2.0, mean 2/3
+        let t = traj(&[&[0.5, 0.5], &[0.5, 0.5], &[0.0, 1.0]]);
+        let r = score_allocation(&t, &AllocationPolicy::default());
+        assert!(r.valid, "{:?}", r.weight_violations);
+        assert!((r.total_turnover - 2.0).abs() < 1e-12);
+        assert!((r.mean_turnover - 2.0 / 3.0).abs() < 1e-12);
+    }
+
+    #[test]
+    fn over_leveraged_vector_flags_gross_exposure() {
+        let t = traj(&[&[0.7, 0.7]]); // gross 1.4 > 1.0 cap
+        let r = score_allocation(&t, &AllocationPolicy::default());
+        assert!(!r.valid);
+        assert!(r.weight_violations.iter().any(|v| matches!(
+            v,
+            WeightViolation::GrossExposureExceeded { cap, .. } if (*cap - 1.0).abs() < 1e-12
+        )));
+    }
+
+    #[test]
+    fn negative_weight_flags_when_shorts_disallowed() {
+        let t = traj(&[&[-0.3, 0.5]]);
+        let r = score_allocation(&t, &AllocationPolicy::default());
+        assert!(!r.valid);
+        assert!(r
+            .weight_violations
+            .iter()
+            .any(|v| matches!(v, WeightViolation::NegativeWeight { index: 0, .. })));
+    }
+
+    #[test]
+    fn shorts_allowed_permits_negative_within_gross_cap() {
+        let policy = AllocationPolicy {
+            allow_shorts: true,
+            max_gross: 2.0,
+            ..Default::default()
+        };
+        let t = traj(&[&[-0.5, 0.5]]); // gross 1.0 <= 2.0
+        let r = score_allocation(&t, &policy);
+        assert!(r.valid, "{:?}", r.weight_violations);
+    }
+
+    #[test]
+    fn non_finite_weight_flags() {
+        let t = traj(&[&[f64::NAN, 0.5]]);
+        let r = score_allocation(&t, &AllocationPolicy::default());
+        assert!(!r.valid);
+        assert!(r
+            .weight_violations
+            .iter()
+            .any(|v| matches!(v, WeightViolation::NonFiniteWeight { index: 0 })));
+    }
+
+    #[test]
+    fn empty_trajectory_is_valid_with_zero_turnover() {
+        let r = score_allocation(
+            &AllocationTrajectory::default(),
+            &AllocationPolicy::default(),
+        );
+        assert!(r.valid);
+        assert_eq!(r.total_turnover, 0.0);
+        assert_eq!(r.mean_turnover, 0.0);
+    }
+}

sharpebench-0.0.13/sharpebench-core/src/attribution.rs

@@ -0,0 +1,60 @@
+//! Performance attribution — separate skill (alpha) from market beta.
+//!
+//! "Return rank = luck" taken one step further: how much of an agent's return is
+//! its own decisions versus simply riding the field/market? We regress an agent's
+//! returns on a market proxy (CAPM-style) and report the intercept (alpha — the
+//! skill component) and slope (beta — market exposure). Computed field-relative in
+//! [`crate::rank`], with the market proxy = the equal-weight average of all
+//! submitted agents' returns. (After KTD-Fin's Barra-style attribution.)
+
+use crate::stats::{mean, variance};
+
+/// CAPM decomposition of `agent` returns against an aligned `market` series.
+/// Returns `(alpha_per_period, beta)`: alpha is the agent's mean return net of its
+/// beta-weighted market exposure — the part that isn't just market drift.
+pub fn alpha_beta(agent: &[f64], market: &[f64]) -> (f64, f64) {
+    let n = agent.len().min(market.len());
+    if n < 2 {
+        return (mean(agent), 0.0);
+    }
+    let a = &agent[..n];
+    let m = &market[..n];
+    let ma = mean(a);
+    let mm = mean(m);
+    let var_m = variance(m);
+    if var_m == 0.0 {
+        return (ma, 0.0);
+    }
+    let cov = a
+        .iter()
+        .zip(m.iter())
+        .map(|(x, y)| (x - ma) * (y - mm))
+        .sum::<f64>()
+        / (n as f64 - 1.0);
+    let beta = cov / var_m;
+    let alpha = ma - beta * mm;
+    (alpha, beta)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn pure_market_follower_has_zero_alpha() {
+        let market: Vec<f64> = (0..50).map(|i| 0.001 * (i as f64 * 0.3).sin()).collect();
+        let agent: Vec<f64> = market.iter().map(|m| 1.5 * m).collect();
+        let (alpha, beta) = alpha_beta(&agent, &market);
+        assert!((beta - 1.5).abs() < 1e-9, "beta={beta}");
+        assert!(alpha.abs() < 1e-9, "alpha={alpha}");
+    }
+
+    #[test]
+    fn constant_excess_is_pure_alpha() {
+        let market: Vec<f64> = (0..50).map(|i| 0.001 * (i as f64 * 0.3).sin()).collect();
+        let agent: Vec<f64> = market.iter().map(|m| m + 0.002).collect();
+        let (alpha, beta) = alpha_beta(&agent, &market);
+        assert!((beta - 1.0).abs() < 1e-9, "beta={beta}");
+        assert!((alpha - 0.002).abs() < 1e-9, "alpha={alpha}");
+    }
+}