conformal-oracle 0.2.1__tar.gz

conformal_oracle-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Traian Pele
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

conformal_oracle-0.2.1/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: conformal-oracle
+Version: 0.2.1
+Summary: Conformal recalibration audit for tail quantile forecasters
+Author-email: Daniel Traian Pele <danpele@ase.ro>
+License-Expression: MIT
+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
+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-0.2.1/README.md

@@ -0,0 +1,105 @@
+# 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
+
+- [Reproduce Table 1 (S&P 500)](examples/notebooks/reproduce_table_1_sp500.ipynb) —
+  GJR-GARCH and Lag-Llama audits with conformal correction on real data.
+
+## 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

conformal_oracle-0.2.1/pyproject.toml

@@ -0,0 +1,93 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "conformal-oracle"
+version = "0.2.1"
+description = "Conformal recalibration audit for tail quantile forecasters"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Daniel Traian Pele", email = "danpele@ase.ro" },
+]
+keywords = ["conformal prediction", "VaR", "risk management", "backtesting"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Mathematics",
+]
+dependencies = [
+    "numpy>=1.24",
+    "pandas>=2.0",
+    "scipy>=1.10",
+    "statsmodels>=0.14",
+    "arch>=6.0",
+    "matplotlib>=3.7",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.1",
+    "mypy>=1.5",
+    "scikit-learn>=1.0",
+]
+chronos = [
+    "chronos-forecasting>=1.5",
+    "torch>=2.0",
+    "transformers>=4.30",
+]
+timesfm = [
+    "timesfm>=1.2",
+    "torch>=2.0",
+]
+moirai = [
+    "uni2ts>=0.1",
+    "torch>=2.0",
+    "einops>=0.6",
+    "gluonts>=0.14",
+    "huggingface-hub>=0.20",
+]
+lag_llama = [
+    "torch>=2.0",
+    "gluonts>=0.14",
+    "huggingface-hub>=0.20",
+    "einops>=0.6",
+]
+tsfm_all = [
+    "chronos-forecasting>=1.5",
+    "timesfm>=1.2",
+    "uni2ts>=0.1",
+    "torch>=2.0",
+    "transformers>=4.30",
+    "gluonts>=0.14",
+    "huggingface-hub>=0.20",
+    "einops>=0.6",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--tb=short -q"
+pythonpath = ["."]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.mypy]
+# v0.1: non-strict. Strict mode has 16 kwargs-forwarding errors — fix in v0.2.
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true

conformal_oracle-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

conformal_oracle-0.2.1/src/conformal_oracle/__init__.py

@@ -0,0 +1,53 @@
+"""Conformal recalibration audit for tail quantile forecasters."""
+
+from conformal_oracle._protocols import Forecaster
+from conformal_oracle._types import (
+    ParametricDistribution,
+    PredictiveDistribution,
+    QuantileGridDistribution,
+    SampleDistribution,
+)
+from conformal_oracle.audit import (
+    audit,
+    audit_rolling,
+    audit_static,
+    audit_with_benchmarks,
+)
+from conformal_oracle.panel import audit_panel
+from conformal_oracle.recalibration import (
+    AdaptiveConformalInference,
+    ConformalShift,
+    ExtremeValueTheoryPOT,
+    FilteredHistoricalSimulation,
+    GBMQuantileRegression,
+    HistoricalQuantileRecalibration,
+    IsotonicQuantileRegression,
+    LinearQuantileRegression,
+    RecalibrationMethod,
+    ScaleCorrectionRecalibration,
+)
+
+__version__ = "0.2.1"
+
+__all__ = [
+    "SampleDistribution",
+    "QuantileGridDistribution",
+    "ParametricDistribution",
+    "PredictiveDistribution",
+    "Forecaster",
+    "audit",
+    "audit_static",
+    "audit_rolling",
+    "audit_with_benchmarks",
+    "audit_panel",
+    "RecalibrationMethod",
+    "ConformalShift",
+    "HistoricalQuantileRecalibration",
+    "ScaleCorrectionRecalibration",
+    "LinearQuantileRegression",
+    "IsotonicQuantileRegression",
+    "AdaptiveConformalInference",
+    "GBMQuantileRegression",
+    "ExtremeValueTheoryPOT",
+    "FilteredHistoricalSimulation",
+]

conformal_oracle-0.2.1/src/conformal_oracle/_conventions.py

@@ -0,0 +1,23 @@
+"""Documented constants and conventions.
+
+Returns: pandas Series of log returns, decimal form (not percent),
+         negative = loss.
+
+VaR sign: VaR is reported as a positive number representing the loss
+          threshold. A violation occurs when r_t < -VaR_t.
+
+Quantile level alpha: small (e.g. 0.01) means the lower-tail probability.
+                      The forecast is the alpha-quantile of the predictive
+                      distribution.
+"""
+
+DEFAULT_ALPHA: float = 0.01
+DEFAULT_CALIBRATION_SPLIT: float = 0.70
+DEFAULT_ROLLING_WINDOW: int = 250
+DEFAULT_WARMUP: int = 250
+DEFAULT_SAMPLE_SIZE: int = 1000
+DEFAULT_BLOCK_LENGTH: int = 20
+DEFAULT_N_BOOT: int = 999
+DEFAULT_SEED: int = 2026
+DEFAULT_PERSISTENCE: int = 20
+REPLACEMENT_THRESHOLD: float = 1.0

conformal_oracle-0.2.1/src/conformal_oracle/_protocols.py

@@ -0,0 +1,27 @@
+"""Forecaster protocol that user implementations must satisfy."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+import pandas as pd
+
+from conformal_oracle._types import PredictiveDistribution
+
+
+class Forecaster(Protocol):
+    """Protocol for one-step-ahead probabilistic forecasters.
+
+    User's forecaster must implement fit() and forecast().
+    """
+
+    def fit(self, returns: pd.Series) -> None:
+        """Fit on calibration data. May be a no-op for zero-shot models."""
+        ...
+
+    def forecast(self, returns: pd.Series, t: int) -> PredictiveDistribution:
+        """One-step-ahead predictive distribution at time t.
+
+        The forecaster sees only returns.iloc[:t] (history up to t-1).
+        """
+        ...

conformal_oracle-0.2.1/src/conformal_oracle/_types.py

@@ -0,0 +1,205 @@
+"""Predictive distribution types used throughout the package."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Union
+
+import numpy as np
+from scipy import stats
+
+
+@dataclass
+class SampleDistribution:
+    """Predictive distribution represented as Monte Carlo samples."""
+
+    samples: np.ndarray
+
+    def quantile(self, alpha: float) -> float:
+        return float(np.quantile(self.samples, alpha))
+
+    def expected_shortfall(self, alpha: float) -> float:
+        q = self.quantile(alpha)
+        tail = self.samples[self.samples <= q]
+        if len(tail) == 0:
+            return q
+        return float(np.mean(tail))
+
+    def cdf(self, x: float) -> float:
+        return float(np.mean(self.samples <= x))
+
+    def __len__(self) -> int:
+        return len(self.samples)
+
+
+@dataclass
+class QuantileGridDistribution:
+    """Predictive distribution as a finite quantile grid."""
+
+    levels: np.ndarray
+    quantiles: np.ndarray
+
+    def quantile(
+        self, alpha: float, completion: str = "student_t"
+    ) -> float:
+        idx_exact = np.where(np.isclose(self.levels, alpha))[0]
+        if len(idx_exact) > 0:
+            return float(self.quantiles[idx_exact[0]])
+
+        if self.levels.min() <= alpha <= self.levels.max():
+            return float(np.interp(alpha, self.levels, self.quantiles))
+
+        return self._tail_completion_quantile(alpha, completion)
+
+    def expected_shortfall(
+        self, alpha: float, completion: str = "student_t"
+    ) -> float:
+        if completion == "linear":
+            return self._es_linear(alpha)
+        params = self._fit_parametric(completion)
+        if completion == "student_t":
+            df, loc, scale = params
+            rv = stats.t(df=df, loc=loc, scale=scale)
+        else:
+            loc, scale = params
+            rv = stats.norm(loc=loc, scale=scale)
+        q = rv.ppf(alpha)
+        tail_samples = rv.rvs(size=10000, random_state=42)
+        tail_samples = tail_samples[tail_samples <= q]
+        if len(tail_samples) == 0:
+            return float(q)
+        return float(np.mean(tail_samples))
+
+    def cdf(self, x: float, completion: str = "student_t") -> float:
+        """CDF evaluated at x. Within the grid range, interpolates
+        between grid points. Outside the grid, uses the same parametric
+        tail completion as quantile() (Student-t by default). Users who
+        want strict in-grid-only behaviour can check
+        ``min(levels) <= cdf_value <= max(levels)`` themselves."""
+        below = self.quantiles[self.quantiles <= x]
+        if len(below) == 0 and x < self.quantiles.min():
+            params = self._fit_parametric(completion)
+            if completion == "student_t":
+                df, loc, scale = params
+                return float(stats.t.cdf(x, df=df, loc=loc, scale=scale))
+            else:
+                loc, scale = params
+                return float(stats.norm.cdf(x, loc=loc, scale=scale))
+        if x >= self.quantiles.max():
+            return 1.0
+        return float(np.interp(x, self.quantiles, self.levels))
+
+    def _tail_completion_quantile(self, alpha: float, method: str) -> float:
+        if method == "linear":
+            if alpha < self.levels.min():
+                slope = (self.quantiles[1] - self.quantiles[0]) / (
+                    self.levels[1] - self.levels[0]
+                )
+                return float(
+                    self.quantiles[0] + slope * (alpha - self.levels[0])
+                )
+            else:
+                slope = (self.quantiles[-1] - self.quantiles[-2]) / (
+                    self.levels[-1] - self.levels[-2]
+                )
+                return float(
+                    self.quantiles[-1] + slope * (alpha - self.levels[-1])
+                )
+
+        params = self._fit_parametric(method)
+        if method == "student_t":
+            df, loc, scale = params
+            return float(stats.t.ppf(alpha, df=df, loc=loc, scale=scale))
+        else:
+            loc, scale = params
+            return float(stats.norm.ppf(alpha, loc=loc, scale=scale))
+
+    def _fit_parametric(self, method: str) -> tuple[float, ...]:
+        if method == "student_t":
+            return self._fit_student_t_quantile()
+        else:
+            loc = float(np.mean(self.quantiles))
+            scale = float(np.std(self.quantiles))
+            return (loc, scale)
+
+    def _fit_student_t_quantile(self) -> tuple[float, float, float]:
+        from scipy.optimize import minimize as _minimize
+
+        levels = self.levels
+        qvals = self.quantiles
+
+        def residuals(params: np.ndarray) -> float:
+            nu, mu, sigma = params
+            if nu <= 2 or sigma <= 0:
+                return 1e10
+            predicted = mu + sigma * stats.t.ppf(levels, nu)
+            return float(np.sum((predicted - qvals) ** 2))
+
+        x0 = [8.0, float(np.median(qvals)), max(float(np.std(qvals)), 1e-8)]
+        res = _minimize(residuals, x0, method="Nelder-Mead",
+                        options={"maxiter": 2000, "xatol": 1e-8})
+        nu, mu, sigma = res.x
+        nu = max(nu, 2.01)
+        sigma = max(sigma, 1e-8)
+        return (nu, mu, sigma)
+
+    def _es_linear(self, alpha: float) -> float:
+        q = self.quantile(alpha, completion="linear")
+        below = self.quantiles[self.levels <= alpha]
+        if len(below) == 0:
+            return float(q)
+        return float(np.mean(np.append(below, q)))
+
+
+@dataclass
+class ParametricDistribution:
+    """Predictive distribution from a closed-form parametric family."""
+
+    location: float
+    scale: float
+    family: Literal["normal", "student_t", "skewed_t"]
+    df: float | None = None
+    skew: float | None = None
+
+    def quantile(self, alpha: float) -> float:
+        rv = self._distribution()
+        return float(rv.ppf(alpha))
+
+    def expected_shortfall(self, alpha: float) -> float:
+        rv = self._distribution()
+        q = rv.ppf(alpha)
+        samples = rv.rvs(size=50000, random_state=42)
+        tail = samples[samples <= q]
+        if len(tail) == 0:
+            return float(q)
+        return float(np.mean(tail))
+
+    def cdf(self, x: float) -> float:
+        rv = self._distribution()
+        return float(rv.cdf(x))
+
+    def _distribution(self) -> stats.rv_continuous:
+        if self.family == "normal":
+            return stats.norm(loc=self.location, scale=self.scale)
+        elif self.family == "student_t":
+            if self.df is None:
+                raise ValueError("df required for student_t family")
+            return stats.t(df=self.df, loc=self.location, scale=self.scale)
+        elif self.family == "skewed_t":
+            if self.df is None or self.skew is None:
+                raise ValueError("df and skew required for skewed_t family")
+            # Hansen's skewed-t: use scipy's nct as approximation
+            return stats.nct(
+                df=self.df,
+                nc=self.skew,
+                loc=self.location,
+                scale=self.scale,
+            )
+        raise ValueError(f"Unknown family: {self.family}")
+
+
+PredictiveDistribution = Union[
+    SampleDistribution,
+    QuantileGridDistribution,
+    ParametricDistribution,
+]

conformal_oracle-0.2.1/src/conformal_oracle/audit/__init__.py

@@ -0,0 +1,55 @@
+"""Audit API: static, rolling, benchmarks, and convenience dispatcher."""
+
+from __future__ import annotations
+
+from typing import Literal, Union
+
+import pandas as pd
+
+from conformal_oracle._protocols import Forecaster
+from conformal_oracle.audit.benchmark import (
+    BenchmarkComparison,
+    audit_with_benchmarks,
+)
+from conformal_oracle.audit.single_rolling import (
+    RollingAuditResult,
+    audit_rolling,
+)
+from conformal_oracle.audit.single_static import (
+    StaticAuditResult,
+    audit_static,
+)
+
+
+def audit(
+    returns: pd.Series,
+    forecaster: Forecaster,
+    alpha: float = 0.01,
+    mode: Literal["static", "rolling"] = "static",
+    recalibration: object | None = None,
+    **kwargs: object,
+) -> Union[StaticAuditResult, RollingAuditResult]:
+    """Convenience dispatcher for static or rolling audit."""
+    if mode == "static":
+        return audit_static(
+            returns, forecaster, alpha=alpha,
+            recalibration=recalibration, **kwargs,
+        )
+    elif mode == "rolling":
+        return audit_rolling(
+            returns, forecaster, alpha=alpha,
+            recalibration=recalibration, **kwargs,
+        )
+    else:
+        raise ValueError(f"Unknown mode: {mode!r}. Use 'static' or 'rolling'.")
+
+
+__all__ = [
+    "audit",
+    "audit_static",
+    "audit_rolling",
+    "audit_with_benchmarks",
+    "StaticAuditResult",
+    "RollingAuditResult",
+    "BenchmarkComparison",
+]