A quant library that refuses to guess.

01What it is

and, just as importantly, what it is not

02The lookahead problem

the flagship feature

A backtest that reads the future does not fail. It succeeds — spectacularly — and tells you nothing. The usual defence is discipline: remember to lag the signal, remember that the rolling mean at t already contains t. Discipline is exactly what fails at 2am.

QuantKit offers three defences instead, and is careful never to conflate them. They differ in kind, not just in strength.

What the audit does catch, reliably, is the entire family of bugs that affect every row — which is nearly all of them in practice:

# each of these has shipped in a real backtest
assert_causal(lambda p: p.rolling(20).mean(), prices)   # passes
assert_causal(lambda p: p.shift(-1), prices)            # LookaheadError
assert_causal(lambda p: p.rolling(21, center=True).mean(), prices)
assert_causal(lambda p: (p - p.mean()) / p.std(), prices)
assert_causal(lambda p: p[::-1].cummax()[::-1], prices)

Data with a reporting lag is declared, and the point-in-time cut respects it — a fundamental filed 45 days after its period end becomes visible 45 days late, not on the date the vendor stamped it:

run_backtest(prices, strategy, panels={
    "fundamentals": Panel("fundamentals", filings,
                            observation_lag=pd.Timedelta(days=45)),
})

Same-bar execution — filling at the close you decided from — is refused unless you pass allow_same_bar=True, so the assumption lands in your code and in the emitted timeline rather than in a footnote nobody reads.

03The execution lag is measured, not asserted

a behavioural check on the engine

With execution_lag=1, a decision made at bar t fills at the close of t+1 — so the first return the new book earns is bar t+2's. That is a testable claim. Give a strategy perfect foresight at each horizon and see where it pays.

04Conventions it refuses to guess

where two libraries disagree on the same data

Two implementations of “annualized volatility” can differ by 5% and neither is wrong — they made different, unstated choices. Every one of these is a named parameter in QuantKit, and every CLI command prints the convention it used alongside the number.

05How it is validated

two kinds of evidence, deliberately kept apart

Independent validation compares a result against something QuantKit did not produce: a third-party library, a literal transcription of a published formula, or a closed-form solution derived analytically. That is the evidence the implementation is right.

Self-consistency validation checks that QuantKit agrees with itself — an identity holds, a fast kernel matches its own exact kernel, a round trip returns its input. These catch real defects, but cannot detect an error shared by both sides. The distinction is marked on every section of the validation document.

The literal transcriptions earned their keep

The reference implementations in the test suite are deliberately slow: explicit double loops, no vectorisation, no shared code with the library. That is what makes agreement meaningful — and it is what caught the worst bug in the project. The vectorised Ledoit–Wolf θ term used Σ x²ᵢ xⱼ where the derivation requires Σ x³ᵢ xⱼ. It produced entirely plausible shrinkage intensities — 0.91 instead of 0.75 — that no eyeball would ever have caught.

Seventeen real defects were found this way in total: seven while writing the tests, ten more in a dedicated adversarial audit before release. Every one shared a shape — a routine returning something that looked like a valid answer where it should have refused. A levered wipeout coming back sign-flipped, so a long position reported as a short. An R² of −15 for a constant series. A single NaN silently poisoning every subsequent row of a rolling window. Each has a regression test written as the smallest case that would have caught it.

06What is in it

eleven modules, one Python API

07Using it

Python API is primary; the CLI is for quick audits

Python 3.10 or newer; numpy, pandas and scipy are the only runtime dependencies.

import quantkit as qk

prices  = qk.data.load_sample_prices()
returns = qk.simple_returns(prices)

qk.sharpe_ratio(returns["ALFA"], risk_free=0.02, freq="daily")   # 1.019
qk.max_drawdown(returns["ALFA"])                                # -0.322
qk.value_at_risk(returns["ALFA"], 0.99)                          # 0.0366 — a loss

result = qk.run_backtest(prices, qk.backtest.EqualWeight(),
                         rebalance="monthly",
                         costs=qk.ProportionalCost(bps=5))
print(result.summary())

$ quantkit metrics   --dataset sample_prices --risk-free 0.02
$ quantkit risk      --dataset sample_prices --confidence 0.99
$ quantkit optimize  --dataset sample_prices --objective min-variance --long-only
$ quantkit backtest  --dataset sample_prices --strategy min-variance --cost-bps 5
$ quantkit lookahead --prices my_prices.csv --window 20 --exhaustive

optimize and lookahead exit non-zero when the optimizer fails to converge or a causality violation is found, so they compose into CI.

08Known limitations

stated plainly, not buried

A correctness claim is only worth what its caveats admit. These are on the front page of the repository too.