alpha-engine-lib 0.47.0__tar.gz → 0.49.0__tar.gz

{alpha_engine_lib-0.47.0/src/alpha_engine_lib.egg-info → alpha_engine_lib-0.49.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: alpha-engine-lib
-Version: 0.47.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.
+Version: 0.49.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, S3-conditional-PUT writer locks, and bounded-backoff HTTP retry. Full surface documented in README.
 Author: Brian McMahon
 License: Proprietary
 Requires-Python: >=3.9
@@ -20,6 +20,10 @@ Provides-Extra: quant-xs
 Requires-Dist: numpy>=1.24; extra == "quant-xs"
 Requires-Dist: pandas>=2.0; extra == "quant-xs"
 Requires-Dist: scikit-learn>=1.0; extra == "quant-xs"
+Provides-Extra: quant-stats
+Requires-Dist: numpy>=1.24; extra == "quant-stats"
+Requires-Dist: pandas>=2.0; extra == "quant-stats"
+Requires-Dist: scipy>=1.7; extra == "quant-stats"
 Provides-Extra: flow-doctor
 Requires-Dist: flow-doctor[diagnosis,s3]<0.5.0,>=0.4.0; extra == "flow-doctor"
 Provides-Extra: rag
@@ -264,6 +268,11 @@ The shared institutional-analytics engine: pure, front-end- and data-source-agno
 - **`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).
+- **`quant.stats`** — strategy/signal-quality evaluation metrics (lifted from the backtester's `analysis/`): `dsr` (Probabilistic + Deflated Sharpe, López de Prado), `information_coefficient` (Spearman rank IC), `expectancy` (hit-rate × win/loss decomposition), `multiple_testing` (Benjamini-Hochberg FDR), `risk_matched_benchmark` (EW-high-vol + beta-matched-SPY baselines + Information Ratio). **Needs pandas + scipy** — `pip install "alpha-engine-lib[quant-stats]"` (scipy is only the IC p-value; numpy fallback otherwise).
+
+### `http_retry` — bounded-backoff transient-API retry chokepoint
+
+`request_with_retry(url, *, params, session, transient_status, ...)` returns the final `requests.Response` after retrying the transient class — 429 + 5xx responses (honoring `Retry-After`) and `Timeout`/`ConnectionError` network errors — with exponential backoff + full jitter; an exhausted network error raises `HttpRetryError` (api-key-scrubbed), while a persistent transient-status response is returned for the caller to interpret (so a 403, not in the transient set, is handed back for e.g. polygon's `PolygonForbiddenError` conversion). Also exposes the low-level `backoff_delay(attempt, *, base, cap, retry_after)` and `scrub_api_keys(msg)` (masks `api_key=`/`apiKey=` querystring values) for consumers with bespoke loops (the rate-limited `polygon_client` keeps its own loop + 403 + JSON parse and reuses just the delay math + scrubber). Consolidates the four mirrored alpha-engine-data retry sites (FRED fetch, polygon client, preflight reachability, FRED repair) into one policy so they stop drifting (L4499). Stdlib + `requests` only.
 
 ```python
 from alpha_engine_lib.quant.risk_measures import historical_cvar

alpha_engine_lib-0.47.0/PKG-INFO → alpha_engine_lib-0.49.0/README.md

@@ -1,38 +1,3 @@
-Metadata-Version: 2.4
-Name: alpha-engine-lib
-Version: 0.47.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
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-Requires-Dist: boto3>=1.34
-Requires-Dist: pydantic>=2.0
-Requires-Dist: pyyaml>=6.0
-Requires-Dist: requests>=2.31
-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: quant-xs
-Requires-Dist: numpy>=1.24; extra == "quant-xs"
-Requires-Dist: pandas>=2.0; extra == "quant-xs"
-Requires-Dist: scikit-learn>=1.0; extra == "quant-xs"
-Provides-Extra: flow-doctor
-Requires-Dist: flow-doctor[diagnosis,s3]<0.5.0,>=0.4.0; extra == "flow-doctor"
-Provides-Extra: rag
-Requires-Dist: psycopg2-binary>=2.9; extra == "rag"
-Requires-Dist: pgvector>=0.2; extra == "rag"
-Requires-Dist: numpy>=1.24; extra == "rag"
-Provides-Extra: rerank
-Requires-Dist: sentence-transformers>=3.0; extra == "rerank"
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0; extra == "dev"
-Requires-Dist: pytest-cov>=4.0; extra == "dev"
-Requires-Dist: moto>=5.0; extra == "dev"
-
 # alpha-engine-lib
 
 > Part of [**Nous Ergon**](https://nousergon.ai) — Autonomous Multi-Agent Trading System. Repo and S3 names use the underlying project name `alpha-engine`.
@@ -264,6 +229,11 @@ The shared institutional-analytics engine: pure, front-end- and data-source-agno
 - **`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).
+- **`quant.stats`** — strategy/signal-quality evaluation metrics (lifted from the backtester's `analysis/`): `dsr` (Probabilistic + Deflated Sharpe, López de Prado), `information_coefficient` (Spearman rank IC), `expectancy` (hit-rate × win/loss decomposition), `multiple_testing` (Benjamini-Hochberg FDR), `risk_matched_benchmark` (EW-high-vol + beta-matched-SPY baselines + Information Ratio). **Needs pandas + scipy** — `pip install "alpha-engine-lib[quant-stats]"` (scipy is only the IC p-value; numpy fallback otherwise).
+
+### `http_retry` — bounded-backoff transient-API retry chokepoint
+
+`request_with_retry(url, *, params, session, transient_status, ...)` returns the final `requests.Response` after retrying the transient class — 429 + 5xx responses (honoring `Retry-After`) and `Timeout`/`ConnectionError` network errors — with exponential backoff + full jitter; an exhausted network error raises `HttpRetryError` (api-key-scrubbed), while a persistent transient-status response is returned for the caller to interpret (so a 403, not in the transient set, is handed back for e.g. polygon's `PolygonForbiddenError` conversion). Also exposes the low-level `backoff_delay(attempt, *, base, cap, retry_after)` and `scrub_api_keys(msg)` (masks `api_key=`/`apiKey=` querystring values) for consumers with bespoke loops (the rate-limited `polygon_client` keeps its own loop + 403 + JSON parse and reuses just the delay math + scrubber). Consolidates the four mirrored alpha-engine-data retry sites (FRED fetch, polygon client, preflight reachability, FRED repair) into one policy so they stop drifting (L4499). Stdlib + `requests` only.
 
 ```python
 from alpha_engine_lib.quant.risk_measures import historical_cvar

{alpha_engine_lib-0.47.0 → alpha_engine_lib-0.49.0}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "alpha-engine-lib"
-version = "0.47.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."
+version = "0.49.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, S3-conditional-PUT writer locks, and bounded-backoff HTTP retry. Full surface documented in README."
 readme = "README.md"
 # EC2 still runs Python 3.9 on the always-on micro instance (boto3 drops
 # 3.9 support 2026-04-29, so upgrade is on the near-term roadmap). All
@@ -39,6 +39,10 @@ quant = ["numpy>=1.24"]
 # separate from [quant] so the numpy-only consumers (e.g. robodashboard)
 # don't pull pandas+sklearn.
 quant-xs = ["numpy>=1.24", "pandas>=2.0", "scikit-learn>=1.0"]
+# Statistical evaluation utilities (alpha_engine_lib.quant.stats — PSR/DSR, IC,
+# expectancy, BH-FDR, risk-matched benchmarks). numpy + pandas always; scipy is
+# used by information_coefficient for the p-value (numpy fallback otherwise).
+quant-stats = ["numpy>=1.24", "pandas>=2.0", "scipy>=1.7"]
 flow_doctor = ["flow-doctor[diagnosis,s3]>=0.4.0,<0.5.0"]
 rag = [
     "psycopg2-binary>=2.9",

{alpha_engine_lib-0.47.0 → alpha_engine_lib-0.49.0}/src/alpha_engine_lib/__init__.py

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

alpha_engine_lib-0.49.0/src/alpha_engine_lib/http_retry.py

@@ -0,0 +1,199 @@
+"""Bounded-backoff HTTP retry primitive — the transient external-API
+resilience chokepoint (L4499).
+
+Consolidates the backoff + full-jitter + ``Retry-After`` + api-key-scrub
+retry idiom that was mirrored across four alpha-engine-data sites:
+
+  * ``collectors/daily_closes.py::_fred_get_with_retry``     (L4480)
+  * ``polygon_client.py::_get`` / ``_backoff``               (L4496)
+  * ``preflight.py::_reachability_get``                      (L4494)
+  * ``collectors/daily_closes_fred_repair.py::_fetch_fred_range``
+
+Each had its own copy of "exponential backoff + full jitter, honor
+``Retry-After``, retry the transient class, scrub the api-key from the
+error before logging/raising, then fail loud." This module is the single
+source of truth for that policy so the four callsites stop drifting.
+
+Two layers are exported:
+
+  * :func:`request_with_retry` — the full GET-with-retry for the plain
+    callsites (FRED fetch, preflight probe, FRED repair). Returns the final
+    ``requests.Response``; the caller still owns status interpretation
+    (``raise_for_status`` / special-casing a 403), so genuinely different
+    consumers compose it without a leaky mega-config.
+  * :func:`backoff_delay` + :func:`scrub_api_keys` — the low-level pieces for
+    a consumer with bespoke control flow (the rate-limited ``polygon_client``
+    keeps its own loop + 403 handling + JSON parse + rate limiter, but shares
+    the delay math and the scrubber).
+
+Design note (anti-over-engineering): this is deliberately NOT a
+pluggable-everything HTTP framework. It captures the one invariant the four
+sites share; consumers whose semantics diverge (polygon's 403 + rate limiter)
+reuse the primitives rather than being forced through a generic loop.
+"""
+
+from __future__ import annotations
+
+import logging as _logging
+import random as _random
+import re
+import time as _time
+from typing import Callable, Iterable
+
+import requests
+
+_DEFAULT_LOGGER = _logging.getLogger(__name__)
+
+# Transient HTTP status class: 429 (rate limit) + the retryable 5xx. A 4xx
+# other than 429 is a deterministic client error — retrying it is pointless,
+# so it is NOT in the default set and is returned to the caller as-is.
+DEFAULT_TRANSIENT_STATUS: "frozenset[int]" = frozenset({429, 500, 502, 503, 504})
+
+# Mask FRED ``api_key=`` (snake) and polygon ``apiKey=`` (camel) querystring
+# VALUES — both leak via ``requests`` exception ``str()`` (the effective URL)
+# and via hand-built error strings. Mirrors the per-repo scrubbers this module
+# replaces; complements ``alpha_engine_lib.logging.SecretsRedactingFilter``
+# (which catches token-shaped secrets, not query-param api keys).
+_API_KEY_RE = re.compile(r"(?:api_key|apiKey)=[^&\s]+")
+
+
+def scrub_api_keys(msg: object) -> str:
+    """Mask ``api_key=...`` / ``apiKey=...`` querystring values in a string.
+
+    Preserves the key NAME (so logs still show *which* param) and the value
+    delimiter, replacing only the secret value with ``***``. Idempotent.
+    """
+    return _API_KEY_RE.sub(lambda m: m.group(0).split("=", 1)[0] + "=***", str(msg))
+
+
+class HttpRetryError(RuntimeError):
+    """Raised when all attempts are exhausted on a transient NETWORK error
+    (``requests.Timeout`` / ``requests.ConnectionError``) or a non-transient
+    ``RequestException``.
+
+    The message is api-key-scrubbed. The originating exception is preserved
+    as ``__cause__`` (and on ``.last_exc``); ``.label`` / ``.attempts`` carry
+    context for callers that want to re-wrap (e.g. preflight's
+    ``RuntimeError(... unreachable ...)``).
+    """
+
+    def __init__(self, label: str, attempts: int, last_exc: BaseException) -> None:
+        self.label = label
+        self.attempts = attempts
+        self.last_exc = last_exc
+        super().__init__(
+            scrub_api_keys(
+                f"{label or 'request'} failed after {attempts} attempt(s): {last_exc}"
+            )
+        )
+
+
+def backoff_delay(
+    attempt: int,
+    *,
+    base: float = 1.0,
+    cap: float = 30.0,
+    retry_after: "str | float | None" = None,
+    rng: "_random.Random | None" = None,
+) -> float:
+    """Full-jitter exponential backoff: ``min(base*2**attempt + U(0, base), cap)``.
+
+    ``attempt`` is 0-indexed. Honors a server ``Retry-After`` (seconds, str or
+    float) when supplied — a numeric value replaces the exponential term (still
+    + jitter, still capped); a non-numeric ``Retry-After`` (HTTP-date form)
+    falls back to the exponential term. ``rng`` is injectable for deterministic
+    tests.
+    """
+    wait: "float | None" = None
+    if retry_after is not None:
+        try:
+            wait = float(retry_after)
+        except (TypeError, ValueError):
+            wait = None
+    if wait is None:
+        wait = base * (2 ** attempt)
+    jitter = (rng or _random).uniform(0, base)
+    return min(wait + jitter, cap)
+
+
+def request_with_retry(
+    url: str,
+    *,
+    method: str = "GET",
+    params: "dict | None" = None,
+    session: "requests.Session | None" = None,
+    timeout: float = 15.0,
+    max_attempts: int = 3,
+    backoff_base: float = 1.0,
+    backoff_cap: float = 30.0,
+    transient_status: Iterable[int] = DEFAULT_TRANSIENT_STATUS,
+    retry_network: bool = True,
+    honor_retry_after: bool = True,
+    scrub: Callable[[object], str] = scrub_api_keys,
+    logger: "_logging.Logger | None" = None,
+    label: str = "",
+    sleep: Callable[[float], None] = _time.sleep,
+) -> requests.Response:
+    """``method`` ``url`` with bounded backoff + full jitter on the transient
+    class, returning the final :class:`requests.Response`.
+
+    Retries:
+      * responses whose status is in ``transient_status`` (default 429 + 5xx),
+        honoring ``Retry-After`` when ``honor_retry_after``; and
+      * (when ``retry_network``) ``requests.Timeout`` / ``ConnectionError``.
+
+    Terminal behavior:
+      * a transient-status response that survives ``max_attempts`` is
+        **returned** — the caller decides whether to ``raise_for_status`` or
+        special-case it (e.g. a 403, which is NOT in the transient set, is
+        returned immediately for the caller to convert); and
+      * an exhausted NETWORK error (or a non-transient ``RequestException``
+        such as a bad URL) raises :class:`HttpRetryError` (scrubbed).
+
+    ``scrub`` is applied to every error string logged or raised. ``session``
+    lets a caller reuse a session (e.g. one carrying auth query params).
+    ``sleep`` is injectable for tests. ``max_attempts`` must be >= 1.
+    """
+    if max_attempts < 1:
+        raise ValueError(f"max_attempts must be >= 1, got {max_attempts}")
+    log = logger or _DEFAULT_LOGGER
+    transient = frozenset(transient_status)
+    requester = (session or requests).request
+    resp: "requests.Response | None" = None
+    for attempt in range(max_attempts):
+        last = attempt == max_attempts - 1
+        try:
+            resp = requester(method, url, params=params or {}, timeout=timeout)
+        except (requests.Timeout, requests.ConnectionError) as exc:
+            if not retry_network or last:
+                raise HttpRetryError(label, attempt + 1, exc) from exc
+            delay = backoff_delay(attempt, base=backoff_base, cap=backoff_cap)
+            log.warning(
+                "%s transient %s — backing off %.1fs (attempt %d/%d)",
+                label or url, type(exc).__name__, delay, attempt + 1, max_attempts,
+            )
+            sleep(delay)
+            continue
+        except requests.RequestException as exc:
+            # Non-transient (bad URL / too many redirects / invalid schema) —
+            # retrying a deterministic error is pointless; fail loud now.
+            raise HttpRetryError(label, attempt + 1, exc) from exc
+
+        if resp.status_code in transient and not last:
+            retry_after = resp.headers.get("Retry-After") if honor_retry_after else None
+            delay = backoff_delay(
+                attempt, base=backoff_base, cap=backoff_cap, retry_after=retry_after,
+            )
+            log.warning(
+                "%s HTTP %d — backing off %.1fs (attempt %d/%d)",
+                label or url, resp.status_code, delay, attempt + 1, max_attempts,
+            )
+            sleep(delay)
+            continue
+        return resp
+
+    # Loop exhausted on transient-status responses: return the last one for the
+    # caller to interpret (network exhaustion already raised above). resp is
+    # non-None because max_attempts >= 1 guarantees at least one assignment.
+    assert resp is not None
+    return resp

alpha_engine_lib-0.49.0/src/alpha_engine_lib/quant/stats/__init__.py

@@ -0,0 +1,22 @@
+"""Statistical evaluation utilities for signal/strategy quality assessment.
+
+Pure-compute metrics consumed across the fleet (backtester, robodashboard) for
+judging signal quality, strategy skill, and selection bias — no I/O. Import the
+submodule you need (the package keeps no eager imports). Most need numpy+pandas;
+``information_coefficient`` additionally uses scipy when present (with a numpy
+fallback). Install ``alpha-engine-lib[quant-stats]``.
+
+Modules:
+  - ``dsr``                     — Probabilistic + Deflated Sharpe (López de Prado)
+  - ``information_coefficient`` — Spearman rank IC of conviction vs forward return
+  - ``expectancy``              — hit-rate × win/loss decomposition
+  - ``multiple_testing``        — Benjamini-Hochberg FDR correction
+  - ``risk_matched_benchmark``  — EW-high-vol + beta-matched-SPY baselines + IR
+
+Example::
+
+    from alpha_engine_lib.quant.stats.dsr import compute_dsr
+    from alpha_engine_lib.quant.stats.multiple_testing import benjamini_hochberg
+"""
+
+from __future__ import annotations

alpha_engine_lib-0.49.0/src/alpha_engine_lib/quant/stats/dsr.py

@@ -0,0 +1,278 @@
+"""dsr — Probabilistic Sharpe Ratio (PSR) and Deflated Sharpe Ratio (DSR).
+
+Confidence-adjusted Sharpe per López de Prado:
+  - PSR (Bailey & López de Prado 2012): probability that the *true* Sharpe
+    is above a benchmark, given the observed sample size + skew + kurtosis.
+    Answers "is this Sharpe distinguishable from the benchmark, given how
+    little data we have?"
+  - DSR (Bailey & López de Prado 2014): PSR with a multiple-testing
+    correction. The benchmark is set to the expected maximum Sharpe under
+    N independent trials, so DSR > 0.95 means "even after accounting for
+    cherry-picking from N candidates, this Sharpe is significant."
+
+The promotion gate for any multiple-testing factory (param sweeps that
+auto-promote the top-Sharpe combo): point-estimate Sharpe on a short sample
+has a wide CI; DSR is what prevents promoting noise winners.
+
+Mathematical reference:
+  Bailey & López de Prado (2012) "The Sharpe Ratio Efficient Frontier"
+  Bailey & López de Prado (2014) "The Deflated Sharpe Ratio: Correcting
+  for Selection Bias, Backtest Overfitting, and Non-Normality"
+
+Pure-compute. Operates on a daily return series + sample-size metadata;
+no I/O.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from typing import TypedDict
+
+import numpy as np
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+_TRADING_DAYS_PER_YEAR = 252
+
+
+class PSRResult(TypedDict, total=False):
+    status: str
+    n: int
+    sharpe: float           # observed annualized Sharpe
+    sharpe_benchmark: float # benchmark Sharpe being tested against
+    psr: float              # probability in [0, 1] that true SR > benchmark
+    skew: float
+    kurtosis: float
+
+
+class DSRResult(TypedDict, total=False):
+    status: str
+    n: int
+    sharpe: float
+    n_trials: int           # number of candidates considered (multiple-testing N)
+    sharpe_benchmark: float # implied benchmark from N_trials under H0: SR=0
+    dsr: float              # probability that the true Sharpe survives selection bias
+    skew: float
+    kurtosis: float
+
+
+def _normal_cdf(x: float) -> float:
+    """Standard normal CDF — pure-Python, no scipy dependency."""
+    return 0.5 * (1.0 + math.erf(x / math.sqrt(2.0)))
+
+
+def _annualized_sharpe(returns: np.ndarray) -> float:
+    """Annualized Sharpe (risk-free = 0), sample-std (ddof=1)."""
+    if returns.size < 2:
+        return 0.0
+    mean = float(returns.mean())
+    std = float(returns.std(ddof=1))
+    if std == 0.0:
+        return 0.0
+    return mean / std * math.sqrt(_TRADING_DAYS_PER_YEAR)
+
+
+def _sample_skew_kurtosis(returns: np.ndarray) -> tuple[float, float]:
+    """Sample skewness and excess kurtosis. Pearson-style; scipy-equivalent.
+
+    Excess kurtosis = K - 3 (so a normal has 0 excess kurtosis).
+    Returns (0, 0) on insufficient sample.
+    """
+    n = returns.size
+    if n < 4:
+        return 0.0, 0.0
+    mean = returns.mean()
+    centered = returns - mean
+    var = float((centered * centered).mean())
+    if var == 0.0:
+        return 0.0, 0.0
+    std = math.sqrt(var)
+    skew = float((centered ** 3).mean() / (std ** 3))
+    kurt_excess = float((centered ** 4).mean() / (var * var)) - 3.0
+    return skew, kurt_excess
+
+
+def compute_psr(
+    daily_returns: pd.Series | np.ndarray,
+    sharpe_benchmark: float = 0.0,
+) -> PSRResult:
+    """Probabilistic Sharpe Ratio.
+
+    Parameters
+    ----------
+    daily_returns : array-like
+        Daily simple returns. NaN dropped.
+    sharpe_benchmark : float
+        Annualized Sharpe to test against (default 0.0, i.e. "is the
+        true SR positive?").
+
+    Returns
+    -------
+    PSRResult dict with:
+        status: "ok" | "insufficient_data"
+        n: sample size
+        sharpe: observed annualized SR
+        sharpe_benchmark: as input
+        psr: probability that true SR > benchmark
+        skew, kurtosis: moments of the return series
+
+    Formula (Bailey & López de Prado 2012):
+        PSR(SR*) = Phi(  (SR_hat - SR*) * sqrt(n - 1)
+                        / sqrt(1 - skew * SR_hat + (kurtosis - 1)/4 * SR_hat^2) )
+
+    where SR_hat is the *non-annualized* observed Sharpe and SR* is the
+    benchmark on the same scale. We compute on daily Sharpe internally
+    and convert benchmarks accordingly.
+    """
+    r = np.asarray(daily_returns, dtype=np.float64)
+    r = r[np.isfinite(r)]
+    n = r.size
+    if n < 30:  # PSR is asymptotic; small samples produce nonsense
+        return {"status": "insufficient_data", "n": n}
+
+    sr_annualized = _annualized_sharpe(r)
+    # PSR formula uses the daily SR. Convert annualized benchmark back to daily.
+    sr_daily = sr_annualized / math.sqrt(_TRADING_DAYS_PER_YEAR)
+    sr_bench_daily = sharpe_benchmark / math.sqrt(_TRADING_DAYS_PER_YEAR)
+
+    skew, kurt_excess = _sample_skew_kurtosis(r)
+    # The "kurtosis" term in López de Prado's formula is the raw 4th
+    # moment / variance^2 (so 3.0 for a normal); we have excess kurtosis.
+    kurt_raw = kurt_excess + 3.0
+
+    denom_sq = 1.0 - skew * sr_daily + (kurt_raw - 1.0) / 4.0 * sr_daily ** 2
+    if denom_sq <= 0.0:
+        # Pathological skew/kurtosis combo; PSR formula breaks down.
+        return {
+            "status": "ok",
+            "n": n,
+            "sharpe": sr_annualized,
+            "sharpe_benchmark": sharpe_benchmark,
+            "psr": 0.5,  # max-uncertainty fallback
+            "skew": skew,
+            "kurtosis": kurt_excess,
+        }
+    z = (sr_daily - sr_bench_daily) * math.sqrt(n - 1) / math.sqrt(denom_sq)
+    psr = _normal_cdf(z)
+
+    return {
+        "status": "ok",
+        "n": n,
+        "sharpe": sr_annualized,
+        "sharpe_benchmark": sharpe_benchmark,
+        "psr": float(psr),
+        "skew": skew,
+        "kurtosis": kurt_excess,
+    }
+
+
+_EULER_MASCHERONI = 0.5772156649015329
+
+
+def compute_dsr(
+    daily_returns: pd.Series | np.ndarray,
+    n_trials: int,
+) -> DSRResult:
+    """Deflated Sharpe Ratio.
+
+    Corrects PSR for the selection bias of choosing the maximum Sharpe
+    from ``n_trials`` candidates. The benchmark Sharpe is set to the
+    expected maximum SR under the null hypothesis (true SR = 0 for all
+    candidates), accounting for sample size + sample moments.
+
+    Parameters
+    ----------
+    daily_returns : array-like
+        Daily returns of the *winner* (the candidate selected as best).
+    n_trials : int
+        Number of candidates considered when selecting this winner. For
+        a 60-combo param sweep, n_trials = 60. Must be >= 1.
+
+    Returns
+    -------
+    DSRResult dict with:
+        status, n, sharpe, n_trials, sharpe_benchmark, dsr, skew, kurtosis
+
+    Formula (Bailey & López de Prado 2014, Theorem 1):
+        E[max(SR)] ≈ V * (sqrt(2 ln N) - (gamma + ln ln N) / (2 sqrt(2 ln N)))
+    where V is the standard deviation of estimated SRs across trials and
+    gamma is Euler-Mascheroni. We approximate V with the sampling std of
+    SR_hat = sqrt((1 - skew*SR + (k-1)/4 * SR^2) / (n - 1)) on the winner.
+
+    DSR = PSR(SR_hat | benchmark = E[max(SR_null)]).
+
+    Notes
+    -----
+    - n_trials = 1 reduces to PSR(0) — no selection correction needed.
+    - For very high n_trials (>1000) the asymptotic expansion above is
+      adequate; for small n (< 5) it overstates the threshold slightly,
+      which is the conservative direction (harder to clear) — fine for
+      a promotion gate.
+    """
+    if n_trials < 1:
+        raise ValueError(f"n_trials must be >= 1, got {n_trials}")
+
+    r = np.asarray(daily_returns, dtype=np.float64)
+    r = r[np.isfinite(r)]
+    n = r.size
+    if n < 30:
+        return {"status": "insufficient_data", "n": n, "n_trials": n_trials}
+
+    if n_trials == 1:
+        # No selection bias correction needed; reduce to PSR(0).
+        psr_result = compute_psr(r, sharpe_benchmark=0.0)
+        return {
+            "status": psr_result["status"],
+            "n": n,
+            "sharpe": psr_result.get("sharpe", 0.0),
+            "n_trials": 1,
+            "sharpe_benchmark": 0.0,
+            "dsr": psr_result.get("psr", 0.5),
+            "skew": psr_result.get("skew", 0.0),
+            "kurtosis": psr_result.get("kurtosis", 0.0),
+        }
+
+    sr_annualized = _annualized_sharpe(r)
+    sr_daily = sr_annualized / math.sqrt(_TRADING_DAYS_PER_YEAR)
+    skew, kurt_excess = _sample_skew_kurtosis(r)
+    kurt_raw = kurt_excess + 3.0
+
+    # Sampling std of SR_hat (per López de Prado eq. 5).
+    var_sr_sq = (1.0 - skew * sr_daily + (kurt_raw - 1.0) / 4.0 * sr_daily ** 2) / (n - 1)
+    if var_sr_sq <= 0.0:
+        return {
+            "status": "ok",
+            "n": n,
+            "sharpe": sr_annualized,
+            "n_trials": n_trials,
+            "sharpe_benchmark": 0.0,
+            "dsr": 0.5,
+            "skew": skew,
+            "kurtosis": kurt_excess,
+        }
+    v = math.sqrt(var_sr_sq)
+
+    # Expected max SR under the null, in daily SR units.
+    ln_n = math.log(n_trials)
+    sqrt_2_ln_n = math.sqrt(2.0 * ln_n)
+    if n_trials > 1:
+        ln_ln_n = math.log(ln_n) if ln_n > 0 else 0.0
+    else:
+        ln_ln_n = 0.0
+    expected_max_sr_daily = v * (sqrt_2_ln_n - (_EULER_MASCHERONI + ln_ln_n) / (2.0 * sqrt_2_ln_n))
+    expected_max_sr_annualized = expected_max_sr_daily * math.sqrt(_TRADING_DAYS_PER_YEAR)
+
+    psr_result = compute_psr(r, sharpe_benchmark=expected_max_sr_annualized)
+
+    return {
+        "status": psr_result["status"],
+        "n": n,
+        "sharpe": sr_annualized,
+        "n_trials": n_trials,
+        "sharpe_benchmark": expected_max_sr_annualized,
+        "dsr": psr_result.get("psr", 0.5),
+        "skew": skew,
+        "kurtosis": kurt_excess,
+    }