Metadata-Version: 2.4
Name: riskhub-engine
Version: 0.1.0
Summary: Pure-Python risk engine: VaR/ES and backtests, credit, XVA, FRTB, liquidity, IRRBB, operational and model risk. No dependencies.
Author: louisdelacour21
License-Expression: MIT
Project-URL: Homepage, https://louisdelacour21.github.io/risk-hub/
Project-URL: Repository, https://github.com/louisdelacour21/risk-python-library
Project-URL: Issues, https://github.com/louisdelacour21/risk-python-library/issues
Project-URL: Risk Hub source, https://github.com/louisdelacour21/risk-hub
Keywords: risk,var,expected-shortfall,backtesting,xva,cva,frtb,credit-risk,model-risk,quant
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# riskhub-engine

The pure-Python risk engine behind [Risk Hub](https://louisdelacour21.github.io/risk-hub/) ([source](https://github.com/louisdelacour21/risk-hub)), packaged as a library.
It covers market, credit, counterparty, FRTB, liquidity, rates, operational and model risk. It uses only the standard library: no NumPy, no SciPy, nothing to compile.

Every function is a line-for-line port of the site's JavaScript engine. The two are checked against each other on shared fixtures, with a relative tolerance of 1e-9 or tighter. That parity suite ships in `tests/parity/`.

```bash
pip install riskhub-engine                                   # once on PyPI
pip install git+https://github.com/louisdelacour21/risk-python-library.git      # from GitHub
```

Python 3.9 or later.

## Quick start

```python
from riskhub_engine import market, credit, options, model_risk

r = market.simulate(1000, seed=7)                       # GARCH-t daily returns
print(market.historical(r[-500:], 0.99))                 # {'var': 0.0243..., 'es': 0.0298...}
print(market.garch(r[-500:], 0.99))                      # GARCH(1,1) VaR / ES with the fitted a, b

bt = market.rolling_backtest(r, "historical", 0.99, 250)
n, x = len(bt["hit"]), sum(bt["hit"])
print(market.kupiec(n, x, 0.01), market.basel_zone(n, x, 0.01))   # {'lr': 1.44, 'p': 0.23} green

m = credit.merton(E=40.0, sigE=0.6, D=80.0, r=0.03, T=1.0)
print(m["pdRN"], m["spread"])                            # risk-neutral PD and credit spread
print(credit.cds_bootstrap([1, 3, 5], [0.010, 0.014, 0.017], 0.03, 0.4))   # piecewise hazard rates

print(options.bs(100, 100, 1.0, 0.2, 0.03, 0.0, "C"))    # price 9.41 and greeks; "P" for a put
print(model_risk.psi(r[:500], r[500:]), model_risk.ks2(r[:500], r[500:]))  # drift between two samples
```

## Modules

| Module | Contents |
|---|---|
| `market` | VaR / ES by nine methods (`METHODS`: historical, normal, Cornish-Fisher, EWMA, EWMA-MLE, GARCH, FHS, age- and vol-weighted). Rolling backtest, Kupiec, Christoffersen, Basel traffic light, ES backtest. Tick loss and Diebold-Mariano, component and incremental VaR, stressed window, expectile and spectral risk |
| `credit` | Merton and KMV, Basel IRB risk weights, CDS bootstrap and pricing, CreditRisk+, rating migration, IFRS 9 ECL, PD backtest |
| `xva` | Swap exposure profile with CVA / DVA / FVA, SA-CCR, KVA / MVA, wrong-way CVA |
| `frtb` | Liquidity-horizon ES, sensitivities-based method, P&L attribution test and zones, curvature, DRC |
| `liquidity` | LCR, NSFR, survival horizon, maturity ladder, FTP, margin calls, Roll / Amihud / Corwin-Schultz / Parkinson |
| `rates` | Discounting, duration, par-to-zero, key-rate DV01, BCBS IRRBB shock scenarios, cross-currency and CDS-bond basis |
| `operational` | Loss distribution approach (VaR, ES, single-loss approximation), scenarios with a Gaussian copula, reverse stress test |
| `portfolio` | Ledoit-Wolf, Marchenko-Pastur cleaning, Higham nearest correlation, HRP, minimum variance, Black-Litterman, Almgren-Chriss |
| `dependence` | Pearson, Spearman, Kendall, distance correlation, mutual information, DCC, copula fit (Gaussian, t, Clayton, Gumbel) |
| `model_risk` | PSI and KS drift, fairness and proxy tests, permutation importance and Shapley, CUSUM and sup-F stability, model tiering, findings rating |
| `quantum` | Shor resource estimates for elliptic curves, Q-Day timing, Mosca's inequality |
| `options` | Black-Scholes-Merton with greeks, implied volatility, Merton jumps, Heston, option book value, greeks and P&L grid |
| `quant` | EVT and Hill, simulation (GBM, jumps, Heston, OU), SVI / SABR, trees, curves, optimisation |
| `econometrics` | OLS with diagnostics, ADF, Engle-Granger, AR / ARMA, GARCH / GJR by maximum likelihood, Granger causality |
| `ml` | Ridge, lasso, logistic, ROC / AUC / KS, trees, boosting, Gaussian HMM, quantile regression |

Each module defines `__all__`, so `help(riskhub_engine.credit)` lists what it contains.

## Conventions

- Inputs are plain Python lists and floats. Results are floats, lists or dicts with named fields.
- VaR and ES are returned as positive losses, in the units of the returns.
- Random draws use seeded generators (Mulberry32, as in the JavaScript engine), so a given seed gives the same numbers in Python and in the browser.

## Tests

```bash
pip install -e .[test]
pytest
```

`tests/test_parity.py` runs the parity scripts `tests/parity/check_*.py` against the JavaScript fixtures. `tests/test_api.py` checks the public modules and runs the quick start above.

## Development

This repository is [risk-python-library](https://github.com/louisdelacour21/risk-python-library). The source of truth is `site/engine/` in the [Risk Hub repository](https://github.com/louisdelacour21/risk-hub), which is also what runs in the browser through Pyodide. `tools/sync_engine.py` regenerates `src/riskhub_engine/` and `tests/parity/` from it. Run it after every engine change, then run `pytest`. The themed modules are declared in `THEMES` in that script.

## Licence

MIT. Not investment advice. The models are teaching and research implementations; validate them before any production use.
