Metadata-Version: 2.4
Name: conformal-finance
Version: 0.1.1
Summary: Uncertainty quantification for financial time series via conformal prediction
Project-URL: Homepage, https://github.com/satyamdas03/conformal-finance
Project-URL: Repository, https://github.com/satyamdas03/conformal-finance
Project-URL: Issues, https://github.com/satyamdas03/conformal-finance/issues
Project-URL: Documentation, https://satyamdas03.github.io/conformal-finance/
Author-email: Satyam Das <satyamdas03@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: conformal-prediction,quantitative-finance,risk-management,time-series,uncertainty-quantification,value-at-risk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.11
Requires-Dist: numpy<3.0,>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.11
Requires-Dist: statsmodels>=0.14
Provides-Extra: all
Requires-Dist: build>=1.0; extra == 'all'
Requires-Dist: matplotlib>=3.7; extra == 'all'
Requires-Dist: mkdocs-material>=9.5; extra == 'all'
Requires-Dist: mkdocs>=1.5; extra == 'all'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'all'
Requires-Dist: mypy>=1.11.0; extra == 'all'
Requires-Dist: plotly>=5.18; extra == 'all'
Requires-Dist: pytest-cov>=4.0; extra == 'all'
Requires-Dist: pytest>=7.0; extra == 'all'
Requires-Dist: ruff>=0.4.0; extra == 'all'
Requires-Dist: twine>=5.0; extra == 'all'
Requires-Dist: yfinance>=0.2.0; extra == 'all'
Provides-Extra: data
Requires-Dist: yfinance>=0.2.0; extra == 'data'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: matplotlib>=3.7; extra == 'dev'
Requires-Dist: mkdocs-material>=9.5; extra == 'dev'
Requires-Dist: mkdocs>=1.5; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'dev'
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: plotly>=5.18; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Requires-Dist: yfinance>=0.2.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7; extra == 'viz'
Requires-Dist: plotly>=5.18; extra == 'viz'
Description-Content-Type: text/markdown

# Conformal Finance

Distribution-free **uncertainty quantification for financial time series**.

> **Mission:** Replace meaningless RMSE metrics with calibrated prediction intervals that maintain valid coverage even when financial regimes shift.

Finance ML usually reports point forecasts. Point forecasts hide tail risk. Conformal prediction gives non-parametric, finite-sample coverage guarantees — but almost no public code targets non-stationary financial data. ConformalFinance does exactly that.

## What you can do with it

- Wrap any point forecast in valid prediction intervals using split, CQR, or rolling conformal prediction.
- Adapt to distribution shift online with adaptive conformal inference (ACI).
- Forecast returns, realized volatility, and VaR with calibrated intervals.
- Diagnose empirical coverage, interval width, and conditional coverage by regime.
- Load real market data (optional `yfinance`) or realistic synthetic AR/GARCH series.
- Visualize coverage and width traces (optional `matplotlib`/`plotly`).

## Install

```bash
pip install conformal-finance
```

For development, docs, and optional data / plotting support:

```bash
pip install -e ".[dev]"
```

## Quickstart

```python
import pandas as pd
from conformal_finance.conformal.split import SplitConformalPredictor
from conformal_finance.data.synthetic import generate_ar_garch_returns

# Realistic synthetic returns
returns = generate_ar_garch_returns(n=2000, seed=42)

# Build a trivial point forecast: yesterday's return
y_true = returns.iloc[1:].reset_index(drop=True)
y_pred = returns.iloc[:-1].reset_index(drop=True)

# Split conformal intervals
cp = SplitConformalPredictor(alpha=0.1)
cp.fit(y_true_cal=y_true.iloc[:500], y_pred_cal=y_pred.iloc[:500])
intervals = cp.predict(y_pred_test=y_pred.iloc[500:])

print(intervals.head())
```

## Design

- **Core conformal methods** are implemented from scratch so the API stays stable and lightweight.
- **Optional extras** (`yfinance`, `matplotlib`, `plotly`) are imported lazily and never required for import.
- **scikit-learn-style interface**: every predictor exposes `.fit()` / `.predict()` or equivalent streaming methods.
- **Type hints and numpy/pandas idioms** throughout.

## Project layout

```
conformal_finance/
├── conformal/       # Split, CQR, ACI, Rolling conformal predictors
├── finance/         # Returns, volatility, VaR conformalizers
├── diagnostics/     # Coverage, width, and regime diagnostics
├── data/            # Synthetic AR/GARCH generators and yfinance loader
└── viz/             # Coverage/width plotting helpers
```

## Documentation

Full docs are built with MkDocs and hosted at https://satyamdas03.github.io/conformal-finance/.

Local build:

```bash
mkdocs serve
```

## Roadmap

| Version | Focus | Status |
|---|---|---|
| v0.1.0 | Split, CQR, ACI, rolling; returns, vol, VaR; diagnostics | In progress |
| v0.2.0 | Realized ES, drawdown, and factor-return targets | Planned |
| v0.3.0 | GARCH / historical-simulation benchmarks | Planned |
| v0.4.0 | Portfolio sizing and vol targeting | Planned |
| v0.5.0 | Research note + integration with FactorForge | Planned |

## License

MIT © 2026 Satyam Das
