Conformal recalibration audit for tail quantile forecasters.
Given any return series and either a forecaster object or a
pre-computed quantile path, conformal-oracle computes a
one-parameter conformal correction (static or rolling), classifies
the forecast as signal-preserving or replacement, and reports a
full backtest panel.
The core install is dependency-agnostic: it needs only NumPy, pandas, SciPy, statsmodels, and matplotlib. No forecaster library is required unless you use the built-in benchmark wrappers.
Implements the methodology from:
Pele, D.T., Bolovaneanu, V., Ginavar, A.T., Lessmann, S., Hardle, W.K. "Recalibrating Tail Event Forecasts under Temporal Dependence" (2026).
pip install conformal-oracle # core (no arch dep)
pip install conformal-oracle[benchmarks] # + GJR-GARCH, GARCH-Normal
pip install conformal-oracle[chronos] # + Chronos TSFM
pip install conformal-oracle[all] # everythingFor development:
git clone https://github.com/QuantLet/Conformal_Oracle.git
cd Conformal_Oracle/python
pip install -e ".[dev,benchmarks]"import pandas as pd
from conformal_oracle import audit
returns = pd.read_csv("returns.csv", index_col=0, parse_dates=True).squeeze()
# q_lo: your model's predicted 1% quantile, same index as returns
q_lo = pd.read_csv("my_var_forecast.csv", index_col=0, parse_dates=True).squeeze()
result = audit(returns, forecast=q_lo, alpha=0.01, mode="static")
print(result.summary())
# Rolling mode: re-estimates the conformal correction in an
# expanding window (more realistic for live deployment)
result_roll = audit(returns, forecast=q_lo, alpha=0.01, mode="rolling")
print(result_roll.summary())No arch, no torch, no heavyweight dependency -- just your
quantile series.
from conformal_oracle import audit
from conformal_oracle.contrib.benchmarks import GJRGARCHForecaster
result = audit(returns, GJRGARCHForecaster(), alpha=0.01, mode="rolling")
print(result.summary())from conformal_oracle import classify_regime
verdict = classify_regime(returns, forecast=q_lo, mode="rolling")
print(verdict.regime) # "signal-preserving" or "replacement"
print(verdict.R) # replacement ratio
print(verdict.basel_zone) # "green", "yellow", or "red"from conformal_oracle import compare_forecasters
comp = compare_forecasters(
returns,
{"model_A": q_lo_A, "model_B": q_lo_B},
mode="rolling",
)
print(comp.comparison_table())
print(comp.dm_matrix())Any object implementing fit(returns) and forecast(returns, t) works:
from conformal_oracle._types import SampleDistribution
class MyForecaster:
def fit(self, returns): pass
def forecast(self, returns, t):
hist = returns.iloc[max(0, t-250):t]
return SampleDistribution(samples=hist.values)
result = audit(returns, MyForecaster(), alpha=0.01)- Quickstart (S&P 500) --
Static and rolling conformal audits with GJR-GARCH and Lag-Llama.
- Reproduce Table 4 (Full replication) --
9 forecasters x 24 assets, full master evaluation table with checkpointing.
- API Reference
- Methodology
- Conventions (return units, VaR sign, alpha)
- Migration Guide (v0.3)
Python 3.10+, numpy, pandas, scipy, statsmodels, matplotlib.
GARCH benchmarks require arch>=6.0 (install with [benchmarks]).
TSFM wrappers require PyTorch and model-specific packages (see extras).
MIT