Metadata-Version: 2.4
Name: alphalens-core
Version: 0.3.3
Summary: AlphaLens — an event-driven backtesting & walk-forward engine for systematic strategies
Author: AlphaLens LLC
License: Apache-2.0
Project-URL: Homepage, https://github.com/AlphaLens-LLC/alphalens-core
Project-URL: Repository, https://github.com/AlphaLens-LLC/alphalens-core
Keywords: backtesting,quant,trading,walk-forward,finance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.24
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7; extra == "viz"
Requires-Dist: quantstats; extra == "viz"
Provides-Extra: polygon
Requires-Dist: polygon-api-client; extra == "polygon"
Provides-Extra: fast
Requires-Dist: pyarrow>=14; extra == "fast"
Provides-Extra: cloud
Requires-Dist: supabase>=2.0; extra == "cloud"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# alphalens-core

**An event-driven backtesting & walk-forward engine for systematic trading strategies.**

Write a strategy as a Python class, run a single forward pass over an in-memory
OHLCV feed, and get back an equity curve, a trade log, and a rich set of
performance statistics — plus walk-forward analysis, parameter sweeps, and an
HTML dashboard. `alphalens-core` is the open engine behind **AlphaLens**.

## Install

```bash
pip install alphalens-core              # core engine (pandas + numpy only)
pip install "alphalens-core[viz]"       # + matplotlib / quantstats dashboard & reports
pip install "alphalens-core[polygon]"   # + Polygon market-data fetching
pip install "alphalens-core[fast]"      # + pyarrow parquet cache
```

## Quickstart

```python
from alphalens_core import Algorithm, Backtester

class GoldenCross(Algorithm):
    start = "2020-01-01"
    end = "2024-12-31"
    universe = ["SPY"]

    def initialize(self):
        self.set_warmup(50)

    def on_data(self, slice):
        hist = self.history("SPY", 50)["close"]
        if len(hist) < 50:
            return
        self.set_holdings("SPY", 1.0 if hist.tail(10).mean() > hist.mean() else 0.0)

result = Backtester().run(GoldenCross)
print(result.stats)     # Sharpe, Sortino, CAGR, max drawdown, win rate, …
result.dashboard        # inline HTML report in Jupyter, or opens in your browser
```

Live data needs a `POLYGON_API_KEY` (a `.env` / `.env.local` file is loaded
automatically). To run fully offline, inject your own `DataFeed`.

## Features

- **Event-driven lifecycle** — `initialize`, `on_data`, `on_order_event`,
  `on_securities_changed`, `on_end_of_day`, `on_warmup_finished`.
- **Realistic fills** — next-bar execution with pluggable slippage / fee / fill
  models, and a one-bar look-ahead guard so decisions on bar *t* can't peek at
  bar *t*'s close.
- **Walk-forward analysis** with per-fold parameter search.
- **Parameter sweeps** + PBO (probability of backtest overfitting).
- **Simulated brokerage** that mirrors a live-broker API, so a live adapter
  drops in without strategy changes.
- **Reporting** — `result.stats`, an HTML `result.dashboard`, and quantstats
  reports.

## CLI

```bash
alphalens run --strategy mymod:MyStrategy
alphalens wfa --strategy mymod:MyStrategy --train 504 --test 63 --step 63
alphalens cache --info
```

## License

[Apache-2.0](LICENSE) © AlphaLens LLC
