Metadata-Version: 2.4
Name: conformal-oracle
Version: 0.2.2
Summary: Conformal recalibration audit for tail quantile forecasters
Author-email: Daniel Traian Pele <danpele@ase.ro>
License-Expression: MIT
Project-URL: Homepage, https://github.com/QuantLet/Conformal_Oracle
Project-URL: Repository, https://github.com/danpele/Conformal_Oracle
Project-URL: Issues, https://github.com/danpele/Conformal_Oracle/issues
Keywords: conformal prediction,VaR,risk management,backtesting
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: statsmodels>=0.14
Requires-Dist: arch>=6.0
Requires-Dist: matplotlib>=3.7
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"
Requires-Dist: scikit-learn>=1.0; extra == "dev"
Provides-Extra: chronos
Requires-Dist: chronos-forecasting>=1.5; extra == "chronos"
Requires-Dist: torch>=2.0; extra == "chronos"
Requires-Dist: transformers>=4.30; extra == "chronos"
Provides-Extra: timesfm
Requires-Dist: timesfm>=1.2; extra == "timesfm"
Requires-Dist: torch>=2.0; extra == "timesfm"
Provides-Extra: moirai
Requires-Dist: uni2ts>=0.1; extra == "moirai"
Requires-Dist: torch>=2.0; extra == "moirai"
Requires-Dist: einops>=0.6; extra == "moirai"
Requires-Dist: gluonts>=0.14; extra == "moirai"
Requires-Dist: huggingface-hub>=0.20; extra == "moirai"
Provides-Extra: lag-llama
Requires-Dist: torch>=2.0; extra == "lag-llama"
Requires-Dist: gluonts>=0.14; extra == "lag-llama"
Requires-Dist: huggingface-hub>=0.20; extra == "lag-llama"
Requires-Dist: einops>=0.6; extra == "lag-llama"
Provides-Extra: tsfm-all
Requires-Dist: chronos-forecasting>=1.5; extra == "tsfm-all"
Requires-Dist: timesfm>=1.2; extra == "tsfm-all"
Requires-Dist: uni2ts>=0.1; extra == "tsfm-all"
Requires-Dist: torch>=2.0; extra == "tsfm-all"
Requires-Dist: transformers>=4.30; extra == "tsfm-all"
Requires-Dist: gluonts>=0.14; extra == "tsfm-all"
Requires-Dist: huggingface-hub>=0.20; extra == "tsfm-all"
Requires-Dist: einops>=0.6; extra == "tsfm-all"
Dynamic: license-file

# conformal-oracle

Conformal recalibration audit for tail quantile forecasters.

Given any black-box probabilistic forecaster and a return series,
`conformal-oracle` computes a one-parameter conformal correction
(static or rolling), classifies the forecaster as signal-preserving
or replacement, and reports a full backtest panel.

Implements the methodology from:

> Pele, D.T., Bolovăneanu, V., Ginavar, A.T., Lessmann, S., Härdle, W.K.
> "Recalibrating Tail Event Forecasts under Temporal Dependence" (2026).

## Install

```bash
pip install conformal-oracle
```

For TSFM wrappers:

```bash
pip install conformal-oracle[chronos]    # Chronos
pip install conformal-oracle[lag_llama]  # Lag-Llama
pip install conformal-oracle[tsfm_all]   # all four TSFMs
```

For development:

```bash
git clone https://github.com/QuantLet/Conformal_Oracle.git
cd Conformal_Oracle/python
pip install -e ".[dev]"
```

## Quickstart — static audit

```python
import pandas as pd
from conformal_oracle import audit_static
from conformal_oracle.forecasters import GJRGARCHForecaster

returns = pd.read_csv("returns.csv", index_col=0, parse_dates=True).squeeze()
result = audit_static(returns, GJRGARCHForecaster(), alpha=0.01)
print(result.summary())
```

## Quickstart — rolling audit

```python
from conformal_oracle import audit_rolling
from conformal_oracle.forecasters import GJRGARCHForecaster

result = audit_rolling(returns, GJRGARCHForecaster(), alpha=0.01, window=250)
print(result.summary())
```

## Quickstart — benchmark comparison

```python
from conformal_oracle import audit_with_benchmarks

comp = audit_with_benchmarks(returns, my_forecaster, benchmarks=["gjr_garch", "hist_sim"])
print(comp.comparison_table())
print(comp.diebold_mariano(baseline="gjr_garch"))
print(comp.comparison_table_latex())
```

## Custom forecaster

Any object implementing `fit(returns)` and `forecast(returns, t)` works:

```python
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_static(returns, MyForecaster(), alpha=0.01)
```

See `examples/04_custom_forecaster.py` for a full example.

## Worked examples

- [Quickstart (S&P 500)](examples/notebooks/quickstart_sp500.ipynb) —
  Static and rolling conformal audits with GJR-GARCH and Lag-Llama.
  [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/danpele/Conformal_Oracle/blob/main/python/examples/notebooks/quickstart_sp500.ipynb)
- [Reproduce Table 4 (Full replication)](examples/notebooks/reproduce_table4_full.ipynb) —
  9 forecasters × 24 assets, full master evaluation table with checkpointing.
  [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/danpele/Conformal_Oracle/blob/main/python/examples/notebooks/reproduce_table4_full.ipynb)

## Documentation

- [API Reference](docs/api.md)
- [Methodology](docs/methodology.md)
- [Conventions](docs/conventions.md) (return units, VaR sign, alpha)

## Requirements

Python 3.10+, numpy, pandas, scipy, statsmodels, arch, matplotlib.

## License

MIT
