trialgate 0.1.0__py3-none-any.whl

trialgate/__init__.py

@@ -0,0 +1,72 @@
+"""trialgate: an anti-overfitting validation gate for backtested strategies.
+
+A strategy earns belief by surviving verification, not by looking good
+in-sample. This package provides the mechanical parts of a six-gate
+qualification standard: an append-only trial registry, CSCV/PBO and
+Deflated Sharpe Ratio statistics, a single-use holdout lock, and threshold
+gates that combine them into a verdict.
+"""
+
+from trialgate.gates import (
+    DEFAULT_MAX_PBO,
+    DEFAULT_MIN_DSR,
+    DEFAULT_MIN_OBSERVATIONS,
+    GateCheck,
+    GateReport,
+    evaluate_gates,
+)
+from trialgate.holdout import (
+    HoldoutState,
+    HoldoutViolationError,
+    initialize_holdout,
+    load_holdout,
+    require_data_allowed,
+    spend_holdout,
+)
+from trialgate.registry import (
+    TrialRecord,
+    TrialRegistryError,
+    append_trial,
+    config_hash_for,
+    load_trials,
+    trial_count,
+)
+from trialgate.validation import (
+    DeflatedSharpeResult,
+    PBOResult,
+    ValidationInputError,
+    deflated_sharpe_ratio,
+    non_annualized_sharpe_variance,
+    probability_of_backtest_overfitting,
+    sharpe_ratio,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_MAX_PBO",
+    "DEFAULT_MIN_DSR",
+    "DEFAULT_MIN_OBSERVATIONS",
+    "DeflatedSharpeResult",
+    "GateCheck",
+    "GateReport",
+    "HoldoutState",
+    "HoldoutViolationError",
+    "PBOResult",
+    "TrialRecord",
+    "TrialRegistryError",
+    "ValidationInputError",
+    "append_trial",
+    "config_hash_for",
+    "deflated_sharpe_ratio",
+    "evaluate_gates",
+    "initialize_holdout",
+    "load_holdout",
+    "load_trials",
+    "non_annualized_sharpe_variance",
+    "probability_of_backtest_overfitting",
+    "require_data_allowed",
+    "sharpe_ratio",
+    "spend_holdout",
+    "trial_count",
+]

trialgate/gates.py

@@ -0,0 +1,99 @@
+"""Threshold gates and the combined qualification report.
+
+The six-gate qualification standard (numbering follows the reference
+deployment, a live crypto signal system):
+
+1. Trial registry (structural)      -> trialgate.registry
+2. Data floor (statistical)         -> judged here
+3. PBO <= 0.05 (statistical)        -> computed by trialgate.validation, judged here
+4. DSR >= 0.95 (statistical)        -> computed by trialgate.validation, judged here
+5. Single-use holdout (structural)  -> trialgate.holdout
+6. Paper trading with measured real costs (procedural) -> out of library
+   scope on purpose: it is a live measurement over months, not a computation.
+
+Passing every gate is a NECESSARY condition for trusting a backtest, not a
+profit guarantee: in a verified 2022 case study the least-overfit strategy
+still lost ~35% in two months.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+DEFAULT_MIN_OBSERVATIONS = 1000
+DEFAULT_MAX_PBO = 0.05
+DEFAULT_MIN_DSR = 0.95
+
+
+@dataclass(frozen=True, slots=True)
+class GateCheck:
+    """One threshold verdict."""
+
+    gate: str
+    passed: bool
+    observed: float
+    threshold: float
+    comparison: str
+
+    def describe(self) -> str:
+        status = "PASS" if self.passed else "FAIL"
+        return f"{status}  {self.gate}: {self.observed:g} {self.comparison} {self.threshold:g}"
+
+
+@dataclass(frozen=True, slots=True)
+class GateReport:
+    """Combined verdict over the statistical gates (2-4)."""
+
+    checks: tuple[GateCheck, ...]
+
+    @property
+    def passed(self) -> bool:
+        return all(check.passed for check in self.checks)
+
+    def summary(self) -> str:
+        lines = [check.describe() for check in self.checks]
+        lines.append("QUALIFIED" if self.passed else "NOT QUALIFIED")
+        return "\n".join(lines)
+
+
+def evaluate_gates(
+    *,
+    observations: int,
+    pbo: float,
+    deflated_sharpe: float,
+    min_observations: int = DEFAULT_MIN_OBSERVATIONS,
+    max_pbo: float = DEFAULT_MAX_PBO,
+    min_dsr: float = DEFAULT_MIN_DSR,
+) -> GateReport:
+    """Judge the statistical gates (2-4) against their thresholds.
+
+    Feed the honest numbers: ``observations`` from the actual data span,
+    ``pbo`` from probability_of_backtest_overfitting() over ALL registered
+    trials, ``deflated_sharpe`` from deflated_sharpe_ratio() using the
+    registry's full trial count. Flattering inputs void the report.
+    """
+
+    checks = (
+        GateCheck(
+            gate="data floor (gate 2)",
+            passed=observations >= min_observations,
+            observed=float(observations),
+            threshold=float(min_observations),
+            comparison=">=",
+        ),
+        GateCheck(
+            gate="PBO (gate 3)",
+            passed=pbo <= max_pbo,
+            observed=pbo,
+            threshold=max_pbo,
+            comparison="<=",
+        ),
+        GateCheck(
+            gate="DSR (gate 4)",
+            passed=deflated_sharpe >= min_dsr,
+            observed=deflated_sharpe,
+            threshold=min_dsr,
+            comparison=">=",
+        ),
+    )
+    return GateReport(checks=checks)

trialgate/holdout.py

@@ -0,0 +1,154 @@
+"""Single-use final holdout lock: iterated out-of-sample is not out-of-sample.
+
+Gate 5 of the six-gate qualification standard. The most recent slice of data
+(typically ~12 months) is locked at first backtest; unlocking is a single-use,
+logged, irreversible event. After the spend, holdout data stays off-limits to
+regular runs forever (Arnott, Harvey & Markowitz 2019).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+
+class HoldoutViolationError(ValueError):
+    """Raised when a run would touch locked or already-spent holdout data."""
+
+
+@dataclass(frozen=True, slots=True)
+class HoldoutState:
+    """Current holdout lock state."""
+
+    holdout_start: datetime
+    locked_at: datetime
+    spent: bool
+    spent_at: datetime | None
+
+    def to_json_dict(self) -> dict[str, object]:
+        return {
+            "holdout_start": self.holdout_start.isoformat(),
+            "locked_at": self.locked_at.isoformat(),
+            "spent": self.spent,
+            "spent_at": self.spent_at.isoformat() if self.spent_at else None,
+        }
+
+
+def initialize_holdout(
+    path: str | Path,
+    *,
+    holdout_start: datetime,
+    locked_at: datetime,
+) -> HoldoutState:
+    """Create the lock once; loading the existing lock on later calls."""
+
+    _require_utc("holdout_start", holdout_start)
+    _require_utc("locked_at", locked_at)
+    existing = load_holdout(path)
+    if existing is not None:
+        return existing
+    state = HoldoutState(
+        holdout_start=holdout_start,
+        locked_at=locked_at,
+        spent=False,
+        spent_at=None,
+    )
+    _write(path, state)
+    return state
+
+
+def load_holdout(path: str | Path) -> HoldoutState | None:
+    """Load the lock state, or None when no lock exists yet."""
+
+    lock_path = Path(path)
+    if not lock_path.exists():
+        return None
+    try:
+        row = json.loads(lock_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        msg = f"holdout lock is corrupt: {lock_path}"
+        raise HoldoutViolationError(msg) from exc
+    if not isinstance(row, dict):
+        msg = f"holdout lock must be a JSON object: {lock_path}"
+        raise HoldoutViolationError(msg)
+    spent_at_raw = row.get("spent_at")
+    return HoldoutState(
+        holdout_start=_parse_utc(str(row["holdout_start"])),
+        locked_at=_parse_utc(str(row["locked_at"])),
+        spent=bool(row["spent"]),
+        spent_at=_parse_utc(str(spent_at_raw)) if spent_at_raw else None,
+    )
+
+
+def require_data_allowed(path: str | Path, *, data_end: datetime) -> None:
+    """Reject any regular run whose data reaches into the holdout period."""
+
+    _require_utc("data_end", data_end)
+    state = load_holdout(path)
+    if state is None:
+        return
+    if data_end >= state.holdout_start:
+        spent_note = (
+            "the holdout has already been SPENT; re-testing against it is void"
+            if state.spent
+            else "unlock it only through the single-use spend procedure"
+        )
+        msg = (
+            f"data_end {data_end.isoformat()} reaches into the locked holdout "
+            f"(starts {state.holdout_start.isoformat()}); {spent_note}"
+        )
+        raise HoldoutViolationError(msg)
+
+
+def spend_holdout(path: str | Path, *, spent_at: datetime) -> HoldoutState:
+    """Mark the single-use holdout as spent. A second spend attempt fails.
+
+    The spend is recorded BEFORE the qualification run executes: if the run
+    crashes, the holdout stays spent (conservative by doctrine).
+    """
+
+    _require_utc("spent_at", spent_at)
+    state = load_holdout(path)
+    if state is None:
+        msg = "cannot spend a holdout that was never initialized"
+        raise HoldoutViolationError(msg)
+    if state.spent:
+        msg = (
+            f"holdout was already spent at "
+            f"{state.spent_at.isoformat() if state.spent_at else 'unknown'}; "
+            "a second use is void (iterated OOS is not OOS)"
+        )
+        raise HoldoutViolationError(msg)
+    spent_state = HoldoutState(
+        holdout_start=state.holdout_start,
+        locked_at=state.locked_at,
+        spent=True,
+        spent_at=spent_at,
+    )
+    _write(path, spent_state)
+    return spent_state
+
+
+def _write(path: str | Path, state: HoldoutState) -> None:
+    lock_path = Path(path)
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    lock_path.write_text(
+        json.dumps(state.to_json_dict(), indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+
+
+def _parse_utc(raw: str) -> datetime:
+    value = datetime.fromisoformat(raw)
+    if value.tzinfo is None:
+        msg = f"holdout timestamps must be timezone-aware: {raw}"
+        raise HoldoutViolationError(msg)
+    return value.astimezone(UTC)
+
+
+def _require_utc(name: str, value: datetime) -> None:
+    if value.tzinfo is None or value.utcoffset() != UTC.utcoffset(value):
+        msg = f"{name} must be timezone-aware UTC"
+        raise HoldoutViolationError(msg)

trialgate/registry.py

@@ -0,0 +1,174 @@
+"""Append-only trial registry: unregistered backtests are void.
+
+Gate 1 of the six-gate qualification standard. Every backtest execution of
+any variant must be recorded here; the registry maintains the running trial
+count N used by the DSR gate. A backtest that does not disclose its trial
+count is worthless by construction (Bailey & Lopez de Prado 2014).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+
+class TrialRegistryError(ValueError):
+    """Raised when the trial registry cannot be read or appended safely."""
+
+
+@dataclass(frozen=True, slots=True)
+class TrialRecord:
+    """One registered backtest execution."""
+
+    trial_id: int
+    recorded_at: datetime
+    config_hash: str
+    code_version: str
+    strategy_id: str
+    parameters: dict[str, str]
+    universe: tuple[str, ...]
+    data_start: datetime
+    data_end: datetime
+    cost_assumptions: dict[str, str]
+    metrics: dict[str, str]
+    operator_note: str
+
+    def to_json_dict(self) -> dict[str, object]:
+        return {
+            "trial_id": self.trial_id,
+            "recorded_at": self.recorded_at.isoformat(),
+            "config_hash": self.config_hash,
+            "code_version": self.code_version,
+            "strategy_id": self.strategy_id,
+            "parameters": dict(self.parameters),
+            "universe": list(self.universe),
+            "data_start": self.data_start.isoformat(),
+            "data_end": self.data_end.isoformat(),
+            "cost_assumptions": dict(self.cost_assumptions),
+            "metrics": dict(self.metrics),
+            "operator_note": self.operator_note,
+        }
+
+
+def config_hash_for(snapshot: dict[str, object]) -> str:
+    """Deterministic SHA-256 of a JSON-serializable config snapshot."""
+
+    canonical = json.dumps(snapshot, sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def trial_count(path: str | Path) -> int:
+    """Current registered trial count N."""
+
+    return len(load_trials(path))
+
+
+def load_trials(path: str | Path) -> tuple[TrialRecord, ...]:
+    """Load every registered trial, oldest first."""
+
+    registry_path = Path(path)
+    if not registry_path.exists():
+        return ()
+    records: list[TrialRecord] = []
+    for line_number, line in enumerate(
+        registry_path.read_text(encoding="utf-8").splitlines(), start=1
+    ):
+        if not line.strip():
+            continue
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError as exc:
+            msg = f"{registry_path}:{line_number} is not valid JSON"
+            raise TrialRegistryError(msg) from exc
+        records.append(_record_from_row(row, registry_path, line_number))
+    return tuple(records)
+
+
+def append_trial(
+    path: str | Path,
+    *,
+    recorded_at: datetime,
+    config_hash: str,
+    code_version: str,
+    strategy_id: str,
+    parameters: dict[str, str],
+    universe: tuple[str, ...],
+    data_start: datetime,
+    data_end: datetime,
+    cost_assumptions: dict[str, str],
+    metrics: dict[str, str],
+    operator_note: str,
+) -> TrialRecord:
+    """Append one trial record and return it with its assigned monotonic id."""
+
+    _require_utc("recorded_at", recorded_at)
+    _require_utc("data_start", data_start)
+    _require_utc("data_end", data_end)
+    if not strategy_id.strip():
+        msg = "strategy_id must not be empty"
+        raise TrialRegistryError(msg)
+    if not universe:
+        msg = "universe must not be empty"
+        raise TrialRegistryError(msg)
+
+    registry_path = Path(path)
+    registry_path.parent.mkdir(parents=True, exist_ok=True)
+    existing = load_trials(registry_path)
+    record = TrialRecord(
+        trial_id=len(existing) + 1,
+        recorded_at=recorded_at,
+        config_hash=config_hash,
+        code_version=code_version,
+        strategy_id=strategy_id,
+        parameters=parameters,
+        universe=universe,
+        data_start=data_start,
+        data_end=data_end,
+        cost_assumptions=cost_assumptions,
+        metrics=metrics,
+        operator_note=operator_note,
+    )
+    with registry_path.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(record.to_json_dict(), sort_keys=True) + "\n")
+    return record
+
+
+def _record_from_row(row: object, path: Path, line_number: int) -> TrialRecord:
+    if not isinstance(row, dict):
+        msg = f"{path}:{line_number} must be a JSON object"
+        raise TrialRegistryError(msg)
+    try:
+        return TrialRecord(
+            trial_id=int(row["trial_id"]),
+            recorded_at=_parse_utc(str(row["recorded_at"])),
+            config_hash=str(row["config_hash"]),
+            code_version=str(row["code_version"]),
+            strategy_id=str(row["strategy_id"]),
+            parameters={str(k): str(v) for k, v in dict(row["parameters"]).items()},
+            universe=tuple(str(v) for v in row["universe"]),
+            data_start=_parse_utc(str(row["data_start"])),
+            data_end=_parse_utc(str(row["data_end"])),
+            cost_assumptions={str(k): str(v) for k, v in dict(row["cost_assumptions"]).items()},
+            metrics={str(k): str(v) for k, v in dict(row["metrics"]).items()},
+            operator_note=str(row["operator_note"]),
+        )
+    except (KeyError, TypeError, ValueError) as exc:
+        msg = f"{path}:{line_number} is not a valid trial record: {exc}"
+        raise TrialRegistryError(msg) from exc
+
+
+def _parse_utc(raw: str) -> datetime:
+    value = datetime.fromisoformat(raw)
+    if value.tzinfo is None:
+        msg = f"trial timestamps must be timezone-aware: {raw}"
+        raise TrialRegistryError(msg)
+    return value.astimezone(UTC)
+
+
+def _require_utc(name: str, value: datetime) -> None:
+    if value.tzinfo is None or value.utcoffset() != UTC.utcoffset(value):
+        msg = f"{name} must be timezone-aware UTC"
+        raise TrialRegistryError(msg)

trialgate/validation.py

@@ -0,0 +1,238 @@
+"""Qualification-gate statistics: Deflated Sharpe Ratio and CSCV/PBO.
+
+Sources:
+- Bailey & Lopez de Prado, "The Deflated Sharpe Ratio" (JPM 2014).
+- Bailey, Borwein, Lopez de Prado & Zhu, "The Probability of Backtest
+  Overfitting" (Journal of Computational Finance 2015).
+
+These statistics operate on measurement floats, not account money, so
+float arithmetic is intentional here (unlike a Decimal trading path).
+"""
+
+from __future__ import annotations
+
+import math
+import statistics
+from dataclasses import dataclass
+from itertools import combinations
+
+_EULER_GAMMA = 0.5772156649015329
+
+
+class ValidationInputError(ValueError):
+    """Raised when gate statistics receive unusable inputs."""
+
+
+@dataclass(frozen=True, slots=True)
+class DeflatedSharpeResult:
+    """DSR output with the inputs that produced it."""
+
+    deflated_sharpe_ratio: float
+    observed_sharpe: float
+    expected_max_sharpe: float
+    effective_trials: int
+    observations: int
+
+
+@dataclass(frozen=True, slots=True)
+class PBOResult:
+    """CSCV output: probability of backtest overfitting."""
+
+    pbo: float
+    combinations_evaluated: int
+    block_count: int
+    strategies: int
+    observations: int
+
+
+def sharpe_ratio(returns: list[float], *, periods_per_year: int = 365) -> float:
+    """Annualized Sharpe ratio of a periodic return series (risk-free = 0)."""
+
+    if len(returns) < 2:
+        return 0.0
+    stdev = statistics.stdev(returns)
+    if stdev == 0.0:
+        return 0.0
+    return statistics.fmean(returns) / stdev * math.sqrt(periods_per_year)
+
+
+def deflated_sharpe_ratio(
+    returns: list[float],
+    *,
+    trial_sharpe_variance: float,
+    effective_trials: int,
+) -> DeflatedSharpeResult:
+    """Probability that the true Sharpe exceeds the expected max of N noise trials.
+
+    ``returns`` are the candidate strategy's periodic (e.g. daily) returns.
+    ``trial_sharpe_variance`` is the variance of (non-annualized) Sharpe ratios
+    across ALL registered trials; ``effective_trials`` is the
+    correlation-adjusted trial count N. Pass the honest numbers from the trial
+    registry — a flattering N voids the gate.
+    """
+
+    if effective_trials < 1:
+        msg = "effective_trials must be at least 1"
+        raise ValidationInputError(msg)
+    if trial_sharpe_variance < 0.0:
+        msg = "trial_sharpe_variance must not be negative"
+        raise ValidationInputError(msg)
+    observations = len(returns)
+    if observations < 3:
+        msg = "returns must contain at least 3 observations"
+        raise ValidationInputError(msg)
+
+    stdev = statistics.stdev(returns)
+    if stdev == 0.0:
+        msg = "returns must not be constant"
+        raise ValidationInputError(msg)
+    observed_sharpe = statistics.fmean(returns) / stdev
+
+    normal = statistics.NormalDist()
+    if effective_trials == 1 or trial_sharpe_variance == 0.0:
+        expected_max_sharpe = 0.0
+    else:
+        spread = math.sqrt(trial_sharpe_variance)
+        expected_max_sharpe = spread * (
+            (1.0 - _EULER_GAMMA) * normal.inv_cdf(1.0 - 1.0 / effective_trials)
+            + _EULER_GAMMA * normal.inv_cdf(1.0 - 1.0 / (effective_trials * math.e))
+        )
+
+    skewness = _skewness(returns)
+    kurtosis = _kurtosis(returns)
+    mertens_term = 1.0 - skewness * observed_sharpe + (kurtosis - 1.0) / 4.0 * observed_sharpe**2
+    if mertens_term <= 0.0:
+        # Fabricating certainty by clamping would answer 0.0/1.0 confidently
+        # on inputs where the variance approximation has broken down.
+        msg = (
+            "returns are too extreme or too short for a stable DSR estimate "
+            f"(Mertens variance term {mertens_term:.6f} <= 0)"
+        )
+        raise ValidationInputError(msg)
+    denominator = math.sqrt(mertens_term)
+    statistic = (
+        (observed_sharpe - expected_max_sharpe) * math.sqrt(observations - 1.0)
+    ) / denominator
+    return DeflatedSharpeResult(
+        deflated_sharpe_ratio=normal.cdf(statistic),
+        observed_sharpe=observed_sharpe,
+        expected_max_sharpe=expected_max_sharpe,
+        effective_trials=effective_trials,
+        observations=observations,
+    )
+
+
+def probability_of_backtest_overfitting(
+    performance_matrix: list[list[float]],
+    *,
+    block_count: int = 16,
+) -> PBOResult:
+    """CSCV estimate of PBO over a T x N trial performance matrix.
+
+    ``performance_matrix``: T rows (periods) x N columns (one per registered
+    trial/configuration), each cell the period return of that configuration.
+    Splits the rows into ``block_count`` contiguous equal blocks, evaluates all
+    C(S, S/2) symmetric train/test partitions, and returns the fraction where
+    the in-sample-best configuration ranks in the bottom half out-of-sample.
+
+    Rows beyond the largest multiple of ``block_count`` — the MOST RECENT
+    ``T mod S`` observations — are dropped to keep blocks equal; compare
+    ``result.observations`` against ``len(performance_matrix)`` to see how
+    many were excluded.
+    """
+
+    if block_count < 2 or block_count % 2 != 0:
+        msg = "block_count must be an even integer of at least 2"
+        raise ValidationInputError(msg)
+    observations = len(performance_matrix)
+    if observations < block_count:
+        msg = "performance_matrix must have at least block_count rows"
+        raise ValidationInputError(msg)
+    strategies = len(performance_matrix[0])
+    if strategies < 2:
+        msg = "performance_matrix must contain at least 2 strategy columns"
+        raise ValidationInputError(msg)
+    if any(len(row) != strategies for row in performance_matrix):
+        msg = "performance_matrix rows must have equal length"
+        raise ValidationInputError(msg)
+
+    usable_rows = observations - (observations % block_count)
+    block_size = usable_rows // block_count
+    block_slices = [
+        performance_matrix[block * block_size : (block + 1) * block_size]
+        for block in range(block_count)
+    ]
+
+    overfit_count = 0
+    combos = list(combinations(range(block_count), block_count // 2))
+    for train_blocks in combos:
+        train_set = frozenset(train_blocks)
+        train_rows = [row for block in sorted(train_set) for row in block_slices[block]]
+        test_rows = [
+            row
+            for block in range(block_count)
+            if block not in train_set
+            for row in block_slices[block]
+        ]
+        train_scores = [_column_sharpe(train_rows, column) for column in range(strategies)]
+        test_scores = [_column_sharpe(test_rows, column) for column in range(strategies)]
+        best_in_sample = max(range(strategies), key=lambda column: train_scores[column])
+        rank = sum(
+            1 for column in range(strategies) if test_scores[column] <= test_scores[best_in_sample]
+        )
+        relative_rank = rank / (strategies + 1)
+        if relative_rank <= 0.5:
+            overfit_count += 1
+
+    return PBOResult(
+        pbo=overfit_count / len(combos),
+        combinations_evaluated=len(combos),
+        block_count=block_count,
+        strategies=strategies,
+        observations=usable_rows,
+    )
+
+
+def _column_sharpe(rows: list[list[float]], column: int) -> float:
+    values = [row[column] for row in rows]
+    if len(values) < 2:
+        return 0.0
+    stdev = statistics.stdev(values)
+    if stdev == 0.0:
+        return 0.0
+    return statistics.fmean(values) / stdev
+
+
+def non_annualized_sharpe_variance(
+    annualized_sharpes: list[float], *, periods_per_year: int = 365
+) -> float:
+    """De-annualize registry Sharpe values into the variance DSR expects.
+
+    The trial registry stores ANNUALIZED Sharpe ratios; feeding their variance
+    into deflated_sharpe_ratio() unconverted inflates the expected-max Sharpe
+    by periods_per_year and false-rejects everything. Var(SR_ann / sqrt(p))
+    equals Var(SR_ann) / p.
+    """
+
+    if len(annualized_sharpes) < 2:
+        return 0.0
+    return statistics.pvariance(annualized_sharpes) / periods_per_year
+
+
+def _skewness(values: list[float]) -> float:
+    # Population moments (ddof=0), matching the paper's gamma_3/gamma_4.
+    mean = statistics.fmean(values)
+    stdev = statistics.pstdev(values)
+    if stdev == 0.0:
+        return 0.0
+    count = len(values)
+    return sum(((value - mean) / stdev) ** 3 for value in values) / count
+
+
+def _kurtosis(values: list[float]) -> float:
+    mean = statistics.fmean(values)
+    stdev = statistics.pstdev(values)
+    if stdev == 0.0:
+        return 3.0
+    count = len(values)
+    return sum(((value - mean) / stdev) ** 4 for value in values) / count

trialgate-0.1.0.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: trialgate
+Version: 0.1.0
+Summary: Anti-overfitting validation gate for backtested trading strategies: append-only trial registry, CSCV/PBO, Deflated Sharpe Ratio, single-use holdout lock.
+Author: Tsai Chih-Chun (0Smallcat0)
+License: MIT
+Project-URL: Repository, https://github.com/0Smallcat0/trialgate
+Project-URL: Issues, https://github.com/0Smallcat0/trialgate/issues
+Project-URL: Reference deployment, https://github.com/0Smallcat0/crypto-quant-signal
+Keywords: backtesting,overfitting,deflated-sharpe-ratio,probability-of-backtest-overfitting,cscv,quantitative-finance,validation,holdout
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: license-file
+
+# trialgate
+
+[![CI](https://github.com/0Smallcat0/trialgate/actions/workflows/ci.yml/badge.svg)](https://github.com/0Smallcat0/trialgate/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![mypy: strict](https://img.shields.io/badge/mypy-strict-blue.svg)](https://mypy.readthedocs.io/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+An **anti-overfitting validation gate** for backtested trading strategies.
+Zero dependencies, pure standard library, fully typed.
+
+> A strategy earns belief by surviving verification, not by looking good
+> in-sample. Optimizing four parameters on a **pure random walk** can produce
+> an in-sample Sharpe of 1.27. A single backtest — however pretty — is not
+> evidence.
+
+`trialgate` packages the mechanical parts of a six-gate qualification
+standard, built from the anti-overfitting literature (Bailey & López de
+Prado, 2014; Bailey, Borwein, López de Prado & Zhu, 2015; Arnott, Harvey &
+Markowitz, 2019):
+
+| Gate | What it enforces | Module |
+|------|------------------|--------|
+| 1. Trial registry | Every backtest of every variant is recorded append-only; unregistered results are void. The registry maintains the honest trial count N. | `trialgate.registry` |
+| 2. Data floor | Enough observations (default ≥ 1,000 daily) spanning real regimes. | `trialgate.gates` |
+| 3. PBO ≤ 0.05 | Probability of Backtest Overfitting via CSCV — all C(S, S/2) symmetric train/test splits. | `trialgate.validation` |
+| 4. DSR ≥ 0.95 | Deflated Sharpe Ratio — the observed Sharpe must beat the expected maximum of N noise trials, adjusted for skew, kurtosis, and sample length. | `trialgate.validation` |
+| 5. Single-use holdout | The most recent data slice is locked at first backtest; spending it is a one-way, logged event. Iterated out-of-sample is not out-of-sample. | `trialgate.holdout` |
+| 6. Paper trading | ≥ 3 months live paper execution with measured real costs. Procedural — deliberately **not** in this library: it is a measurement, not a computation. | — |
+
+Passing all six is a **necessary condition, not a profit guarantee**: in a
+verified 2022 case study, the least-overfit strategy still lost ~35% in two
+months.
+
+## Install
+
+```bash
+pip install trialgate
+```
+
+## Quickstart
+
+```python
+from datetime import UTC, datetime
+
+from trialgate import (
+    append_trial, config_hash_for, load_trials, trial_count,
+    initialize_holdout, require_data_allowed,
+    deflated_sharpe_ratio, probability_of_backtest_overfitting,
+    non_annualized_sharpe_variance, evaluate_gates,
+)
+
+NOW = datetime.now(tz=UTC)
+
+# Gate 5 — lock the most recent ~12 months BEFORE the first backtest.
+initialize_holdout(
+    "state/holdout.json",
+    holdout_start=datetime(2025, 7, 1, tzinfo=UTC),
+    locked_at=NOW,
+)
+# Every regular run must prove it stays out of the holdout.
+require_data_allowed("state/holdout.json", data_end=datetime(2025, 6, 30, tzinfo=UTC))
+
+# Gate 1 — register EVERY backtest execution, including the quick ones.
+append_trial(
+    "state/registry.jsonl",
+    recorded_at=NOW,
+    config_hash=config_hash_for({"lookbacks": [20, 65, 150, 200]}),
+    code_version="8b91661",
+    strategy_id="daily_trend_ensemble",
+    parameters={"lookbacks": "20,65,150,200"},
+    universe=("BTCUSDT", "ETHUSDT"),
+    data_start=datetime(2019, 1, 1, tzinfo=UTC),
+    data_end=datetime(2025, 6, 30, tzinfo=UTC),
+    cost_assumptions={"round_trip_bps": "25"},
+    metrics={"annualized_sharpe": "1.10"},
+    operator_note="baseline",
+)
+
+# Gates 3 + 4 — computed over ALL registered trials, never a flattering subset.
+trials = load_trials("state/registry.jsonl")
+annualized = [float(t.metrics["annualized_sharpe"]) for t in trials]
+
+pbo = probability_of_backtest_overfitting(performance_matrix, block_count=16)
+dsr = deflated_sharpe_ratio(
+    candidate_daily_returns,
+    trial_sharpe_variance=non_annualized_sharpe_variance(annualized),
+    effective_trials=trial_count("state/registry.jsonl"),
+)
+
+# Gates 2-4 combined verdict.
+report = evaluate_gates(
+    observations=len(candidate_daily_returns),
+    pbo=pbo.pbo,
+    deflated_sharpe=dsr.deflated_sharpe_ratio,
+)
+print(report.summary())
+# PASS  data floor (gate 2): 1848 >= 1000
+# PASS  PBO (gate 3): 0.02 <= 0.05
+# PASS  DSR (gate 4): 0.97 >= 0.95
+# QUALIFIED
+```
+
+`performance_matrix` is a T×N list of per-period returns, one column per
+registered configuration; `candidate_daily_returns` is the candidate's daily
+return series. Both come from your backtest engine — `trialgate` judges, it
+does not backtest.
+
+## The gate's job is to say no
+
+This library is extracted from a live system and has one verdict of each kind
+on record:
+
+- **Reference deployment (in progress)** —
+  [crypto-quant-signal](https://github.com/0Smallcat0/crypto-quant-signal):
+  a daily crypto trend-signal system currently spending its locked holdout
+  and 90-day paper period against these exact gates.
+- **A registered FAIL** —
+  [tw-stock-trading](https://github.com/0Smallcat0/tw-stock-trading): the
+  same strategy family adapted to the Taiwan 0050 ETF **failed its
+  pre-registered claim** (CAGR trailed dividend-included buy-and-hold by
+  5.3 pp/year over 21 years; even the zero-cost upper bound barely reached
+  the tolerance line). Per the pre-registered rule, the runtime was never
+  built. The FAIL report *is* the product.
+  Full story: [docs/rejecting-my-own-strategy.md](docs/rejecting-my-own-strategy.md).
+
+## Design notes
+
+- **Zero dependencies.** Standard library only; frozen, slotted dataclasses;
+  ships `py.typed` and passes `mypy --strict`.
+- **UTC or it didn't happen.** Naive datetimes are rejected everywhere.
+- **Raises instead of clamping.** When the DSR variance approximation breaks
+  down, you get an exception, not a confident 0.0/1.0.
+- **Append-only state.** The registry is a JSONL log; the holdout lock is a
+  one-way JSON file. Both are plain text you can audit in any editor.
+- **Judgement, not orchestration.** Bring your own backtest engine and data;
+  the library never touches an exchange or a price feed.
+
+## Provenance
+
+The gate specification, thresholds, and doctrine were defined and verified by
+the author from the primary literature; implementation was AI-assisted
+(spec-driven development with Claude), with every module reviewed against the
+spec and covered by tests before acceptance. This mirrors the library's own
+thesis: artifacts earn trust through verification, not through how they were
+produced.
+
+## References
+
+- Bailey & López de Prado — *The Deflated Sharpe Ratio* (Journal of Portfolio
+  Management, 2014)
+- Bailey, Borwein, López de Prado & Zhu — *The Probability of Backtest
+  Overfitting* (Journal of Computational Finance, 2015)
+- Arnott, Harvey & Markowitz — *A Backtesting Protocol in the Era of Machine
+  Learning* (Journal of Financial Data Science, 2019)
+
+## License
+
+[MIT](LICENSE) © Tsai Chih-Chun (0Smallcat0)

trialgate-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+trialgate/__init__.py,sha256=6tmzuO32gW-sblSdEPXn12rOm96LOf3E40topxuO_rw,1747
+trialgate/gates.py,sha256=jlL0iE8T4Voa1_uGMe2Fa57nnXDLJcNUCVKJXPL49Iw,3100
+trialgate/holdout.py,sha256=YCKoMmRi8gfrVyc1k7mll88hMSTrM7m3_idyUCrWmg4,5024
+trialgate/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+trialgate/registry.py,sha256=inD8K6AyizeD2tzaG6eGNgwrWWB5O_GObwsD7IAW90M,5967
+trialgate/validation.py,sha256=LiWLA8GpBiHMBCHKfJDpgNhFCX_tt0MfvdXoYt9otaY,8532
+trialgate-0.1.0.dist-info/licenses/LICENSE,sha256=dOZv3mDP0a8anlsJ2WiLh7zW5PqbyOBJZFQVOjhl0AU,1084
+trialgate-0.1.0.dist-info/METADATA,sha256=N_j56e3tPcVAInYEstLw5itKXTZJmWPoD8K-7fo0r9w,8351
+trialgate-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+trialgate-0.1.0.dist-info/top_level.txt,sha256=r3qAHzkr1waBBe_tV_GzxslJhJxdgDWmROh8NE8s8f8,10
+trialgate-0.1.0.dist-info/RECORD,,

trialgate-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

trialgate-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tsai Chih-Chun (0Smallcat0)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

trialgate-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+trialgate