Metadata-Version: 2.4
Name: pyrisklib
Version: 0.2.0
Summary: A Python library for financial risk management and analysis
Home-page: https://github.com/piper0124/pyrisklib
Author: YONG LI
Author-email: YONG LI <55830785+piper0124@users.noreply.github.com>
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/piper0124/pyrisklib
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: pandas>=1.3
Requires-Dist: scipy>=1.7
Requires-Dist: tqdm>=4.60
Requires-Dist: plotly>=5.0
Requires-Dist: matplotlib>=3.4
Requires-Dist: scikit-learn>=1.0
Requires-Dist: optuna>=3.0
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# pyrisklib

A Python library for risk management and analysis in financial industries.

**pyrisklib** provides a unified framework for modeling, calibrating, and visualizing risk across
credit, market, and operational domains. The **credit risk module** is currently functional;
market risk and operational risk modules are on the roadmap.

## Features

The **credit risk module** is the core of pyrisklib and is fully functional; market and operational risk are on the roadmap (see below).

### Credit Risk (`credit_risk/`)

- **Default Models** — model families (structural, reduced-form, mixture, actuarial, and accounting-based) that model obligor default and produce the **portfolio credit-loss distribution**, from which **Value-at-Risk (VaR)** and **Expected Shortfall (ES)** are derived.
- **Default Correlation Estimation** — eleven estimators (moment-matching + maximum-likelihood) that calibrate inter-obligor default correlation from observed data.
- **Rating & Transition** — rating management, simulation & validation, default statistics, and transition-matrix estimation.
- **Risk Attribution** — decompose portfolio loss into per-obligor contributions (Monte Carlo + saddlepoint).
- **Basel IRB Capital** — internal-ratings-based asset correlation, capital requirements, and granularity adjustments.

> A complete, always-current index of every class, module, and public export is maintained in **`Framework.xlsx`** (repository root). Refer to it for the full catalogue instead of maintaining duplicate tables here.

### Utilities (`utils/`)

- `common_utils` — `align_to_common_index`, `align_balance_sheet_to_market`, `matching_series`
- `common_plot` — `plot_multiple_time_series`

### Visualization (`risk_visualization/`)

- `risk_attribution_plotter` — `RiskAttributionPlotter`
- `var_plotter` — `VaRPlotter`

## Installation

```bash
pip install pyrisklib
```

Requires Python ≥ 3.8 and:

- numpy ≥ 1.20
- pandas ≥ 1.3
- scipy ≥ 1.7
- tqdm ≥ 4.60
- plotly ≥ 5.0
- matplotlib ≥ 3.4
- scikit-learn ≥ 1.0
- optuna ≥ 3.0

## Project Structure

```text
pyrisklib/
├── __init__.py
├── setup.py
├── README.md
├── LICENSE
├── credit_risk/
│   ├── __init__.py
│   ├── independent_default_model.py
│   ├── threshold_default_model.py
│   ├── mixture_default_model.py
│   ├── market_based_default_model.py
│   ├── statistic_based_default_model.py
│   ├── credit_risk_plus_default_model.py
│   ├── default_correlation_estimator.py
│   ├── credit_rating_manager.py
│   ├── credit_rating_simulator.py
│   ├── rating_default_statistics.py
│   ├── transition_matrix_estimator.py
│   ├── risk_attribution.py
│   └── basel_irb_capital_requirements.py
├── market_risk/           # Market risk models (coming soon)
├── operational_risk/      # Operational risk models (coming soon)
├── risk_visualization/
│   ├── __init__.py
│   ├── risk_attribution_plotter.py
│   └── var_plotter.py
├── utils/
│   ├── __init__.py
│   ├── common_utils.py
│   └── common_plot.py
├── tests/                 # Jupyter notebook-based tests (local only)
├── data/                  # Sample datasets (local only)
```

## Roadmap

- **Market Risk** (`market_risk/`) — VaR/CVaR estimation, volatility models, interest rate risk, FX risk
- **Operational Risk** (`operational_risk/`) — loss distribution approach, scenario analysis, operational loss modeling
- Enhanced visualization and reporting utilities
- CI/CD and automated test suite

## References

- **Bolder, D. J. (2018).** *Credit-Risk Modelling: Theoretical Foundations, Diagnostic Tools, Practical Examples, and Numerical Recipes in Python.* 
  
- **Bandyopadhyay, A. (2016).** *Managing Portfolio Credit Risk in Banks.* Cambridge University Press. ISBN 978-1-107-14647-1.
  
**Foundational models** (algorithmic/mathematical principles, not code): Merton (1974) — structural default model; Vasicek (1987) — loan portfolio loss distribution; Altman (1968) — Z-score discriminant model; Basel Committee on Banking Supervision — Internal Ratings-Based (IRB) framework.

## License

This project is licensed under the **Apache License, Version 2.0** — see [LICENSE](LICENSE) for details.

Apache-2.0 is chosen to align with the scientific computing ecosystem (numpy, scikit-learn, QuantLib) while providing an explicit patent grant and patent retaliation clause for additional legal protection.

## Author

YONG LI — [GitHub](https://github.com/piper0124/pyrisklib)
