[ult666666]

What changes

quantkit computed VaR and CVaR but could not tell whether a VaR model is any good. This PR adds quantkit.var, the validation loop risk teams and bank supervisors use:

• Rolling forecasts (rolling_var_es): one-day VaR and expected shortfall (ES) by historical simulation, a Gaussian model, EWMA (RiskMetrics, decay 0.94) and filtered historical simulation (FHS), with a configurable window and confidence level. A forecast for day t uses only returns t - h .. t - 1. Every method is one location-scale model, r[t] = mu[t] + sigma[t] e[t], which defines VaR, ES and RiskForecast.simulate.
• Exception backtests: Kupiec's proportion-of-failures test (LR_uc), Christoffersen's independence (LR_ind) and conditional coverage (LR_cc) tests, with p-values. Statistics stay finite with no exceptions, only exceptions or no consecutive pairs (0 log 0 = 0). null_rejection_rates computes each test's exact size with a dynamic program over the exception sequence.
• Basel traffic light (basel_traffic_light): zones and plus factors from Table 2 of the Basel Committee's 1996 backtesting framework, for 250 days of 99% VaR.
• ES backtest (es_backtest): Acerbi and Székely's (2014) Z2, with a Monte Carlo p-value from a null simulated from the forecasts themselves.
• CLI and examples: quantkit var-backtest prices.csv --method ewma --level 0.99, examples/var_backtest.py (figure on synthetic GARCH data) and examples/var_size_power.py (size and power study). CI runs both scripts and the new command.
• README, DESIGN (new section 6), CHANGELOG, limits and roadmap updated. The historical-VaR tail count moved to a shared helper (no result changes).

Verification

• uv run pytest --cov=quantkit: 434 passed (345 before), coverage 99.62% (99.50% before), every new module at 100%. ruff check, ruff format --check, mypy --strict clean. README doctests include a new VaR example.
• Independent checks: each rolling window equals historical_var / parametric_var on that window; EWMA equals the RiskMetrics recursion; FHS equals a Hull-White rescaling loop; Kupiec equals SciPy binomial log-likelihoods (Hypothesis); p-values equal scipy.stats.chi2.sf; LR_cc = LR_uc(days 2..T) + LR_ind; exact sizes equal brute-force enumeration of all 2^T sequences; Basel cumulative probabilities equal binom.cdf(k, 250, 0.01) to the published two decimals.
• No look-ahead: changing the scored return and all later ones leaves every forecast through that day bit-identical for all four methods; a peeking forecaster fails the same check. Returns older than the history do not matter either.
• Closed forms on i.i.d. data: historical simulation's exception probability is m / (window + 1) (3/251 at 99%, 250 days); the Gaussian method's is a Student-t prediction probability (1.479% for a 30-day window).
• Size (returns drawn from the EWMA model, so forecasts are exact): the forecasts recover the model volatility to 1e-12 and exceptions equal z < -2.326 exactly; rejection rates match the exact sizes, 9.5% (LR_uc), 1.4% (LR_ind), 1.1% (LR_cc) at 250 days, and 5% for Z2.
• Power (uv run python examples/var_size_power.py, 1,000 paths): Gaussian VaR on Student-t(4) returns over 1,000 days is rejected by LR_uc in 46.9%, LR_cc in 31.3% and Z2 in 87.3% of paths, against 2.2%, 0.9% and 3.9% on normal returns. At 97.5% the exception tests reject 3.4% while Z2 rejects 43.3%.
• Mutation check: 15 injected bugs (look-ahead window, reversed EWMA weights, ddof=0, FHS standardized by the next day's volatility, ES formula, missing factor 2, wrong pooling in LR_ind, chi2(1) for LR_cc, <= exceptions, DP pair counting, two Basel table errors, Z2 without +1, wrong p-value tail, null not simulated) each fail at least one test.

Limits

• One-day horizon and a single return series in return units: no multi-day scaling, position-level P&L or option revaluation.
• EWMA decay is fixed, not estimated; FHS filters with EWMA, not a fitted GARCH.
• LR p-values are asymptotic. null_rejection_rates reports the true size (9.5% for nominal 5% Kupiec at 250 days, 99%), but exact or Monte Carlo p-values are on the roadmap, as are duration-based tests.
• The traffic light covers the 1996 table (250 days, 99%), not the FRTB 97.5% zones or P&L attribution.
• Z2's null is simulated from each method's own forecast distribution, which is discrete for historical simulation and FHS.

---

Generated by Claude Code