alphaengine 0.1.0__py3-none-any.whl

alphaengine/sweep/runner.py

@@ -0,0 +1,321 @@
+"""The grid runner.
+
+WHAT THIS DELIBERATELY DOES NOT DO
+    It does not backtest. `sweep()` takes YOUR function and calls it once per
+    parameter combination. We orchestrate and measure; you simulate. Shipping a
+    backtester would mean competing with the engine you already trust, and
+    inheriting responsibility for its correctness, which is not a trade worth
+    making for a library whose entire claim is that its numbers are reliable.
+
+WHY THE TRIAL COUNT IS NOT A PARAMETER
+    Because a parameter is a place to be optimistic. `n_trials` is `len(grid)`,
+    computed from the grid actually iterated, and there is no argument to
+    override it. That is the single design decision this module exists for.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import itertools
+import json
+import math
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import numpy.typing as npt
+
+from ..core import deflated_sharpe, min_track_record_length, pbo_cscv, performance_report
+
+__all__ = ["sweep", "SweepResult"]
+
+# A parameter set is a plain dict; a returns series is a sequence of floats.
+Params = Mapping[str, Any]
+Returns = Sequence[float]
+BacktestFn = Callable[..., Returns]
+
+
+def _expand(grid: Mapping[str, Iterable[Any]]) -> list[dict[str, Any]]:
+    """Cartesian product of the grid, in a deterministic order.
+
+    Sorted by key so the same grid produces the same ordering on any machine and
+    any Python version, the trial index is part of what gets recorded, so it
+    cannot depend on dict iteration order.
+    """
+    keys = sorted(grid)
+    if not keys:
+        # itertools.product() with no iterables yields ONE empty tuple, so an
+        # empty grid would quietly run once and report n_trials=1. That is
+        # exactly the flattering count this module exists to prevent, so it has
+        # to fail rather than pass.
+        return []
+    values = [list(grid[k]) for k in keys]
+    empty = [k for k, v in zip(keys, values, strict=True) if not v]
+    if empty:
+        # One empty axis makes the whole product empty. A caller who wrote
+        # {"fast": []} meant to sweep something and should hear about it.
+        raise ValueError(f"grid axis has no values: {empty}")
+    return [dict(zip(keys, combo, strict=True)) for combo in itertools.product(*values)]
+
+
+def _hash_data(data: Any) -> str:
+    """Content hash of the input series.
+
+    This is the segment identity, and it is deliberately NOT a user-supplied
+    label: a name can be changed to escape a history, an array cannot. Two runs
+    over the same data are recognisably the same segment even if the researcher
+    renamed the experiment.
+    """
+    try:
+        arr = np.asarray(data, dtype=float)
+        return hashlib.sha256(np.ascontiguousarray(arr).tobytes()).hexdigest()[:16]
+    except (TypeError, ValueError):
+        # Not array-shaped (a dict of price series, say). Hash a canonical
+        # JSON rendering so the identity is still stable across runs.
+        blob = json.dumps(data, sort_keys=True, default=str).encode()
+        return hashlib.sha256(blob).hexdigest()[:16]
+
+
+def _hash_params(p: Params) -> str:
+    return hashlib.sha256(json.dumps(dict(p), sort_keys=True, default=str).encode()).hexdigest()[:12]
+
+
+def _sharpe(returns: npt.NDArray[np.float64]) -> float:
+    sd = float(returns.std(ddof=1)) if returns.size > 1 else 0.0
+    return float(returns.mean() / sd) if sd > 0 else 0.0
+
+
+@dataclass
+class Trial:
+    """One parameter set and what it produced."""
+
+    index: int
+    params: dict[str, Any]
+    params_hash: str
+    n_obs: int
+    sharpe: float
+    sharpe_annualized: float
+    total_return_pct: float
+    failed: str | None = None
+
+
+@dataclass
+class SweepResult:
+    """Everything the sweep saw. The trial matrix is the irreplaceable part."""
+
+    trials: list[Trial]
+    matrix: npt.NDArray[np.float64] = field(repr=False)  # (T observations, N configurations)
+    data_hash: str = ""
+    grid_keys: list[str] = field(default_factory=list)
+    store_params: bool = False
+
+    @property
+    def n_trials(self) -> int:
+        """Derived, never supplied. This is the whole point of the module."""
+        return len(self.trials)
+
+    @property
+    def best(self) -> Trial:
+        return max((t for t in self.trials if t.failed is None), key=lambda t: t.sharpe)
+
+    def verdict(self, *, risk_free_rate: float = 0.0) -> dict[str, Any]:
+        """Deflate the best result for the search that actually produced it.
+
+        PBO is reported alongside but is NOT the gate. It answers a different
+        question, "was the choice AMONG configurations informative?", and
+        returns roughly 0.5 for genuinely near-tied top configs even when the
+        underlying edge is real. Measured on our own null/edge fixture, DSR
+        discriminates cleanly and PBO does not; treating them as two readings of
+        the same thing would be a mistake.
+        """
+        best = self.best
+        col = self.matrix[:, best.index]
+        dsr = deflated_sharpe(col.tolist(), n_trials=self.n_trials)
+        out: dict[str, Any] = {
+            "n_trials": self.n_trials,
+            "n_trials_source": "derived_from_grid",
+            "best_trial_index": best.index,
+            "best_params_hash": best.params_hash,
+            "data_hash": self.data_hash,
+            "deflated_sharpe": dsr.get("deflated_sharpe"),
+            "verdict": dsr.get("verdict"),
+            "psr_vs_zero": dsr.get("psr_vs_zero"),
+            "sr0_expected_max": dsr.get("sr0_expected_max"),
+            "performance": performance_report(col.tolist(), risk_free_rate=risk_free_rate),
+        }
+        if self.store_params:
+            out["best_params"] = best.params
+
+        # Minimum track record length: how long this record must be before the
+        # result is distinguishable from luck. Bites universally, and converts
+        # into a dated obligation rather than a pass/fail insult.
+        try:
+            out["min_track_record_length"] = min_track_record_length(col.tolist())
+        except Exception:  # noqa: BLE001 - never fail a verdict on an optional figure
+            out["min_track_record_length"] = None
+
+        # PBO needs at least two configurations; a single-point "sweep" cannot
+        # say anything about selection, and should say so rather than emit a
+        # number that looks like an answer.
+        if self.matrix.shape[1] >= 2:
+            out["selection"] = {
+                "question": "was the choice among configurations informative?",
+                "not_a_verdict_on_the_edge": True,
+                **pbo_cscv(self.matrix.tolist()),
+            }
+        return out
+
+    def save(
+        self, path: str | Path = "study.json", *, label: str = "", data_description: str = "", notes: str = ""
+    ) -> Path:
+        """Write the study to disk. Local file, no account, no upload."""
+        from ..study import Study
+        from ..study import save as _save
+
+        study = Study.from_sweep(self, label=label, data_description=data_description, notes=notes)
+        return _save(study, path)
+
+    def surface(self) -> dict[str, Any]:
+        """The neighbourhood: plateau or knife edge.
+
+        The payoff of running a grid, and the reason this is a coaching output
+        rather than a refereeing one, a researcher ends the session knowing
+        where to re-centre, not merely that their number was flattered.
+        """
+        ok = [t for t in self.trials if t.failed is None]
+        if not ok:
+            return {"shape": "empty", "n_ok": 0, "n_failed": len(self.trials)}
+
+        sharpes = np.array([t.sharpe for t in ok], dtype=float)
+        best = float(sharpes.max())
+        median = float(np.median(sharpes))
+        # Share of the grid that holds up near the best result. A broad plateau
+        # is robustness; one spike is a result fitted to its own parameters.
+        near = float((sharpes >= best * 0.8).mean()) if best > 0 else 0.0
+        shape = "plateau" if near >= 0.30 else "ridge" if near >= 0.10 else "knife_edge"
+
+        # Where the robust region sits, per parameter, the actionable half.
+        centre: dict[str, Any] = {}
+        if self.store_params:
+            strong = [t for t in ok if best > 0 and t.sharpe >= best * 0.8]
+            for k in self.grid_keys:
+                vals = [t.params.get(k) for t in strong]
+                numeric = [v for v in vals if isinstance(v, (int, float)) and not isinstance(v, bool)]
+                if numeric:
+                    centre[k] = {"median": float(np.median(numeric)), "range": [min(numeric), max(numeric)]}
+
+        return {
+            "shape": shape,
+            "n_ok": len(ok),
+            "n_failed": len(self.trials) - len(ok),
+            "best_sharpe": round(best, 4),
+            "median_sharpe": round(median, 4),
+            "share_within_20pct_of_best": round(near, 4),
+            "plateau_centre": centre or None,
+            "reading": {
+                "plateau": "A broad region performs. The result does not depend on the exact parameters.",
+                "ridge": "A narrow region performs. Sensitive to the parameters; treat with care.",
+                "knife_edge": "One configuration performs and its neighbours do not. "
+                "Usually a fitted result.",
+            }[shape],
+        }
+
+
+def sweep(
+    backtest_fn: BacktestFn,
+    grid: Mapping[str, Iterable[Any]],
+    *,
+    data: Any = None,
+    store_params: bool = False,
+    on_error: str = "record",
+) -> SweepResult:
+    """Run `backtest_fn` once per combination in `grid`.
+
+    Args:
+        backtest_fn: YOUR backtest. Called as ``backtest_fn(data=data, **params)``
+            when `data` is given, otherwise ``backtest_fn(**params)``. Must
+            return a sequence of per-period returns.
+        grid: parameter name -> values to try. The cartesian product is the
+            search, and its length is the trial count.
+        data: passed through untouched. Only hashed, never inspected or stored.
+        store_params: keep the parameter values in the result. OFF by default.
+            THE GRID IS OFTEN BIGGER IP THAN THE RETURN SERIES: "it uploads my
+            parameter search" ends a conversation faster than "it uploads my
+            returns". Hashes are always kept, so runs remain comparable without
+            the values leaving.
+        on_error: "record" marks a failing combination and continues (the
+            default, because one bad corner of a grid should not lose the
+            other ninety-nine results); "raise" propagates.
+
+    Returns:
+        SweepResult, holding the full (T x N) trial matrix that PBO needs and
+        that a single-point run structurally cannot produce.
+    """
+    combos = _expand(grid)
+    if not combos:
+        raise ValueError("grid is empty: nothing to sweep")
+
+    data_hash = _hash_data(data) if data is not None else ""
+    trials: list[Trial] = []
+    columns: list[npt.NDArray[np.float64]] = []
+
+    for i, params in enumerate(combos):
+        try:
+            raw = backtest_fn(data=data, **params) if data is not None else backtest_fn(**params)
+            r = np.asarray(list(raw), dtype=float)
+            if r.ndim != 1 or r.size == 0:
+                raise ValueError(f"backtest_fn returned shape {r.shape}; expected a 1-D return series")
+            if not np.all(np.isfinite(r)):
+                r = np.nan_to_num(r, nan=0.0, posinf=0.0, neginf=0.0)
+        except Exception as exc:  # noqa: BLE001
+            if on_error == "raise":
+                raise
+            trials.append(
+                Trial(
+                    i,
+                    dict(params),
+                    _hash_params(params),
+                    0,
+                    0.0,
+                    0.0,
+                    0.0,
+                    failed=f"{type(exc).__name__}: {exc}",
+                )
+            )
+            continue
+
+        sr = _sharpe(r)
+        trials.append(
+            Trial(
+                index=i,
+                params=dict(params),
+                params_hash=_hash_params(params),
+                n_obs=int(r.size),
+                sharpe=round(sr, 6),
+                sharpe_annualized=round(sr * math.sqrt(252), 4),
+                total_return_pct=round((float(np.prod(1 + r)) - 1) * 100, 4),
+            )
+        )
+        columns.append(r)
+
+    if not columns:
+        raise RuntimeError(
+            f"every one of the {len(combos)} combinations failed. First error: {trials[0].failed}"
+        )
+
+    # Ragged output means the configurations are not comparable, and silently
+    # truncating would produce a PBO over series that do not line up in time.
+    lengths = {c.size for c in columns}
+    if len(lengths) > 1:
+        n = min(lengths)
+        columns = [c[-n:] for c in columns]
+
+    return SweepResult(
+        trials=trials,
+        matrix=np.column_stack(columns),
+        data_hash=data_hash,
+        grid_keys=sorted(grid),
+        store_params=store_params,
+    )

alphaengine-0.1.0.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: alphaengine
+Version: 0.1.0
+Summary: Validated research tooling for investment strategies: deflation, overfitting detection, and honest trial counts.
+Project-URL: Homepage, https://github.com/quantOSC/alphaengine
+Project-URL: Documentation, https://github.com/quantOSC/alphaengine#readme
+Project-URL: Source, https://github.com/quantOSC/alphaengine
+Project-URL: Issues, https://github.com/quantOSC/alphaengine/issues
+Author: QuantOS
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: backtesting,deflated-sharpe,overfitting,quantitative-finance,research
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.10
+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: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: agents
+Requires-Dist: anthropic>=0.40; extra == 'agents'
+Provides-Extra: connectors
+Requires-Dist: httpx>=0.27; extra == 'connectors'
+Requires-Dist: pyarrow>=15.0; extra == 'connectors'
+Provides-Extra: dev
+Requires-Dist: mypy==2.3.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.16.1; extra == 'dev'
+Requires-Dist: statsmodels>=0.14; extra == 'dev'
+Provides-Extra: factors
+Requires-Dist: statsmodels>=0.14; extra == 'factors'
+Description-Content-Type: text/markdown
+
+# AlphaEngine
+
+Validated research tooling for investment strategies. Run a parameter search,
+get back the shape of the result and an honest read on whether it survives the
+number of things you tried.
+
+```bash
+pip install alphaengine
+```
+
+```python
+from alphaengine import sweep
+
+r = sweep(backtest_fn, {"fast": [5, 10, 20], "slow": [50, 100, 200]}, data=prices)
+
+r.surface()    # is the result a broad plateau or a single lucky configuration?
+r.verdict()    # deflated for the 9 trials that were actually run
+r.save()       # study.json, on your disk
+```
+
+## What it does
+
+**Runs your parameter grid.** `sweep()` calls your backtest function once per
+combination. It does not backtest anything itself, so the engine you already
+trust stays the engine you trust.
+
+**Counts the trials for you.** The statistics that correct a Sharpe ratio for
+multiple testing need to know how many variants were tested. That number is
+almost never recorded, because nobody counts what they discarded. Running the
+grid makes it `len(grid)`, so it never has to be asked for or asserted.
+
+**Shows you the neighbourhood.** The output is whether your result sits on a
+broad plateau or a knife edge, and where the robust region is centred. A single
+spike surrounded by failures is a result fitted to its own parameters.
+
+**Produces a portable study.** A JSON artifact holding what was tried, what came
+back, and a content hash of the data it ran on. Readable in a text editor,
+diffable, and versioned so it still parses in two years.
+
+## What is in it
+
+| Module | Contents |
+|---|---|
+| `alphaengine.core` | deflated Sharpe, PSR, PBO via CSCV, CPCV, minimum track record length, performance and risk statistics |
+| `alphaengine.sweep` | the grid runner and the sensitivity surface |
+| `alphaengine.study` | the study artifact and its schema |
+
+Two runtime dependencies, numpy and scipy, both already present in a typical
+research environment. `import alphaengine` makes no network call and needs no
+account. Factor decomposition and cointegration testing need statsmodels and
+are available as `pip install 'alphaengine[factors]'`.
+
+## Where this sits in QuantOS
+
+AlphaEngine is the open research layer of the [QuantOS](https://github.com/quantOSC)
+platform. It is the piece that runs on your machine, against your data, and it
+is complete on its own: everything above works offline and forever, at no cost.
+
+The QuantOS platform builds on it. Studies produced here can be persisted to a
+firm's record, referenced when an idea becomes a position, and assembled into
+the reports that go to an investment committee or an allocator. The library
+computes; the platform remembers and reports. The two halves are separated so
+that the part touching your data has no reason to phone home.
+
+## The methods
+
+Everything in `core` comes from the published literature. Nothing here is a
+proprietary formula, which is deliberate: a referee whose reasoning you cannot
+inspect is not a referee.
+
+**Deflated Sharpe Ratio, Probabilistic Sharpe Ratio, minimum track record length**
+Bailey, D. H., and López de Prado, M. (2012). "The Sharpe Ratio Efficient
+Frontier." *Journal of Risk* 15(2), 3 to 44.
+Bailey, D. H., and López de Prado, M. (2014). "The Deflated Sharpe Ratio:
+Correcting for Selection Bias, Backtest Overfitting, and Non-Normality."
+*Journal of Portfolio Management* 40(5), 94 to 107.
+
+**Probability of Backtest Overfitting via CSCV**
+Bailey, D. H., Borwein, J., López de Prado, M., and Zhu, Q. J. (2017). "The
+Probability of Backtest Overfitting." *Journal of Computational Finance* 20(4),
+39 to 69.
+
+**Combinatorial purged cross-validation**
+López de Prado, M. (2018). *Advances in Financial Machine Learning.* Wiley,
+chapters 7 and 12.
+
+**Multiple testing in asset pricing**
+Harvey, C. R., Liu, Y., and Zhu, H. (2016). "... and the Cross-Section of
+Expected Returns." *Review of Financial Studies* 29(1), 5 to 68.
+Harvey, C. R., and Liu, Y. (2015). "Backtesting." *Journal of Portfolio
+Management* 42(1), 13 to 28.
+
+**Downside deviation**
+Sortino, F. A., and Price, L. N. (1994). "Performance Measurement in a Downside
+Risk Framework." *Journal of Investing* 3(3), 59 to 64.
+
+**Factor regression standard errors** (in the `factors` extra)
+Newey, W. K., and West, K. D. (1987). "A Simple, Positive Semi-Definite,
+Heteroskedasticity and Autocorrelation Consistent Covariance Matrix."
+*Econometrica* 55(3), 703 to 708.
+
+**Unit root testing for cointegration** (in the `factors` extra)
+Dickey, D. A., and Fuller, W. A. (1979). "Distribution of the Estimators for
+Autoregressive Time Series with a Unit Root." *Journal of the American
+Statistical Association* 74(366), 427 to 431.
+
+## Reproducibility
+
+The values these functions return are treated as a public contract. A study
+written today has to reproduce in two years, so a change to a computed value is
+a breaking change requiring a major version bump even when the signature is
+unchanged. CI fails if a pinned value moves.
+
+## Licence
+
+Apache-2.0. See [LICENSE](LICENSE).

alphaengine-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+alphaengine/__init__.py,sha256=Xx64Qohlj9rNdzIpqpA12wXYhHfktMnergnpG1SD-AM,1954
+alphaengine/_version.py,sha256=XAZ3PfMXxfgHsM8709CVeHw2zdqPFtgcuFRTKh8VvlI,651
+alphaengine/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+alphaengine/core/__init__.py,sha256=2rrUJrvTp6GElFeGVQSk0wkszcw2JMTQFyxryVMVJpM,2312
+alphaengine/core/backtest.py,sha256=25bjrygUMhPc4Fg1dCUqcCQah92KQkPm3PedOuQGsXg,28609
+alphaengine/core/factors.py,sha256=uR0seow6x3_Vshp-MkyRQ7WXZB144rV0Ik5Hh15A378,5291
+alphaengine/core/pairs.py,sha256=F3DHM3krXJKZQlK1NMaq1xG9_Td27RyHO3_C9w9Ve3k,20170
+alphaengine/core/performance.py,sha256=HajHtKpJHGVPHlsz70XnsCKvru-swpecU4s9dXJOsgE,4401
+alphaengine/core/risk.py,sha256=xrnfcWE-95LQYDSN9unnjMRGUD0mZHC3AXh6dg459jw,5023
+alphaengine/core/technical.py,sha256=FCK1Hv_yaBjGgOQO6vW9DC4iyJZGww9ST3MUPZ58WWU,7699
+alphaengine/core/validation.py,sha256=cNkNfcdCsXQxgxMM0WDemmVnO2jubfQHcc9Nq21mOGs,14841
+alphaengine/study/__init__.py,sha256=YWR8049WTzPbYvG-IYnj6IVsx_P0ceYKOXYVzzLc3mw,1480
+alphaengine/study/schema.py,sha256=BMKzp11-4SRlu23qw7EqYKrMkacvHjE9orzlcKFv4K8,6381
+alphaengine/sweep/__init__.py,sha256=TQ1w5v6Lb7_CNOC4NJC-Z64jWlUM5q7R-g0agCqNFoQ,803
+alphaengine/sweep/runner.py,sha256=09T_bO4gl22ksIKJfYWPWzvFuM3waXuEx6XxEQpIzPI,13037
+alphaengine-0.1.0.dist-info/METADATA,sha256=5WRceP3yRJrbBspEsJ16Aq6DhYUdWfSj8Lq3RtWrcgM,6817
+alphaengine-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+alphaengine-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+alphaengine-0.1.0.dist-info/RECORD,,

alphaengine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any