Metadata-Version: 2.4
Name: merton
Version: 1.0.2
Summary: Production-grade Merton structural credit-risk model and extensions.
Project-URL: Documentation, https://merton.readthedocs.io
Project-URL: Source, https://github.com/ItsSypher/merton
Project-URL: Issues, https://github.com/ItsSypher/merton/issues
Project-URL: Changelog, https://github.com/ItsSypher/merton/blob/main/CHANGELOG.md
Project-URL: Author, https://itskavy.vercel.app/
Author-email: Kavy Upadhyay <upadhyaykavy@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: basel,black-cox,credit-risk,creditgrades,default-probability,distance-to-default,finance,geske,kmv,merton,structural,vasicek
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: array-api-compat>=1.9
Requires-Dist: joblib>=1.4
Requires-Dist: numba>=0.63
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.2
Requires-Dist: platformdirs>=4.3
Requires-Dist: pyarrow>=15
Requires-Dist: pydantic-settings>=2.5
Requires-Dist: pydantic>=2.8
Requires-Dist: rich>=13.7
Requires-Dist: scipy>=1.13
Requires-Dist: structlog>=24.4
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer>=0.12
Requires-Dist: typing-extensions>=4.12
Provides-Extra: all
Requires-Dist: arviz>=0.20; extra == 'all'
Requires-Dist: blpapi>=3.24; extra == 'all'
Requires-Dist: cupy-cuda12x>=13.3; extra == 'all'
Requires-Dist: emcee>=3.1; extra == 'all'
Requires-Dist: fastapi>=0.115; extra == 'all'
Requires-Dist: httpx2>=2.3; extra == 'all'
Requires-Dist: jax>=0.4.35; extra == 'all'
Requires-Dist: jaxlib>=0.4.35; extra == 'all'
Requires-Dist: jinja2>=3.1; extra == 'all'
Requires-Dist: matplotlib>=3.9; extra == 'all'
Requires-Dist: openpyxl>=3.1; extra == 'all'
Requires-Dist: opentelemetry-api>=1.27; extra == 'all'
Requires-Dist: opentelemetry-exporter-otlp>=1.27; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.27; extra == 'all'
Requires-Dist: pandas-datareader>=0.10; extra == 'all'
Requires-Dist: plotly>=5.24; extra == 'all'
Requires-Dist: seaborn>=0.13; extra == 'all'
Requires-Dist: uvicorn[standard]>=0.32; extra == 'all'
Requires-Dist: xlsxwriter>=3.2; extra == 'all'
Requires-Dist: xlwings>=0.33; extra == 'all'
Requires-Dist: yfinance>=0.2.40; extra == 'all'
Provides-Extra: bench
Requires-Dist: asv>=0.6; extra == 'bench'
Requires-Dist: pytest-benchmark>=4.0; extra == 'bench'
Requires-Dist: pytest-codspeed>=3.0; extra == 'bench'
Provides-Extra: bloomberg
Requires-Dist: blpapi>=3.24; extra == 'bloomberg'
Provides-Extra: data
Requires-Dist: pandas-datareader>=0.10; extra == 'data'
Requires-Dist: yfinance>=0.2.40; extra == 'data'
Provides-Extra: dev
Requires-Dist: bandit[toml]>=1.7; extra == 'dev'
Requires-Dist: beartype>=0.19; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: codespell>=2.3; extra == 'dev'
Requires-Dist: hypothesis>=6.115; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: nox>=2024.10; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pytest-benchmark>=4.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-randomly>=3.15; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.7; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2024.8; extra == 'docs'
Requires-Dist: myst-nb>=1.1; extra == 'docs'
Requires-Dist: myst-parser<5,>=4.0; extra == 'docs'
Requires-Dist: sphinx-autoapi>=3.3; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
Requires-Dist: sphinx-design>=0.6; extra == 'docs'
Requires-Dist: sphinx<9,>=8.1; extra == 'docs'
Requires-Dist: sphinxcontrib-bibtex>=2.6; extra == 'docs'
Provides-Extra: excel
Requires-Dist: fastapi>=0.115; extra == 'excel'
Requires-Dist: httpx2>=2.3; extra == 'excel'
Requires-Dist: jinja2>=3.1; extra == 'excel'
Requires-Dist: openpyxl>=3.1; extra == 'excel'
Requires-Dist: uvicorn[standard]>=0.32; extra == 'excel'
Requires-Dist: xlsxwriter>=3.2; extra == 'excel'
Requires-Dist: xlwings>=0.33; extra == 'excel'
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x>=13.3; extra == 'gpu'
Provides-Extra: jax
Requires-Dist: jax>=0.4.35; extra == 'jax'
Requires-Dist: jaxlib>=0.4.35; extra == 'jax'
Provides-Extra: mcmc
Requires-Dist: arviz>=0.20; extra == 'mcmc'
Requires-Dist: emcee>=3.1; extra == 'mcmc'
Provides-Extra: mlx
Requires-Dist: mlx>=0.21; (platform_system == 'Darwin' and platform_machine == 'arm64') and extra == 'mlx'
Provides-Extra: obs
Requires-Dist: opentelemetry-api>=1.27; extra == 'obs'
Requires-Dist: opentelemetry-exporter-otlp>=1.27; extra == 'obs'
Requires-Dist: opentelemetry-sdk>=1.27; extra == 'obs'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.9; extra == 'viz'
Requires-Dist: plotly>=5.24; extra == 'viz'
Requires-Dist: seaborn>=0.13; extra == 'viz'
Description-Content-Type: text/markdown

# merton

[![PyPI version](https://img.shields.io/pypi/v/merton?cacheSeconds=300)](https://pypi.org/project/merton/)
[![Python versions](https://img.shields.io/pypi/pyversions/merton?cacheSeconds=300)](https://pypi.org/project/merton/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/ItsSypher/merton/blob/main/LICENSE)
[![CI](https://github.com/ItsSypher/merton/actions/workflows/test.yml/badge.svg)](https://github.com/ItsSypher/merton/actions/workflows/test.yml)
[![Docs](https://readthedocs.org/projects/merton/badge/?version=latest)](https://merton.readthedocs.io)
[![DOI](https://zenodo.org/badge/1243573447.svg)](https://doi.org/10.5281/zenodo.20309589)
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Typed](https://img.shields.io/badge/typed-mypy-blue.svg)](http://mypy-lang.org/)

A production-grade Python package for the **Merton structural credit-risk model**
and its industry-standard descendants (KMV, Black-Cox, Geske, Longstaff-Schwartz,
CreditGrades, Leland-Toft, jump-diffusion, Vasicek portfolio, climate overlays).

> **🚀 New in 1.0** — first stable release. API frozen per [semver](https://merton.readthedocs.io/en/latest/contributing/api-stability.html),
> cold `import merton` down to ~500 ms (from ~1.1 s), conda-forge feedstock in
> review. See the [announcement post](https://merton.readthedocs.io/en/latest/blog/announcing-1.0.html)
> and the [migration guide](https://merton.readthedocs.io/en/latest/contributing/migrating-to-1.0.html).

## Highlights

- **Vectorized core** — single-firm and panel-scale (10 000+ firms × decades)
  with NumPy by default and optional Numba / JAX / CuPy / MLX backends.
- **Multiple calibration methods** — Vassalou-Xing iterative MLE, Duan
  transformed-data MLE (with survivorship-bias correction), Jones-Mason-Rosenfeld,
  Bharath-Shumway naive, KMV iterative (Crosbie-Bohn).
- **Full extensions library** — Black-Cox first-passage, Geske compound options,
  Longstaff-Schwartz stochastic rates, CreditGrades, Leland-Toft endogenous
  default, Zhou jump-diffusion, hybrid structural/reduced-form, climate overlays.
- **Portfolio engine** — Vasicek single-factor (Basel IRB closed-form),
  Gaussian / t / Clayton / factor copulas, Monte Carlo loss distribution with
  VaR / ES / economic capital.
- **Backtesting harness** — AUC, Brier, KS, accuracy ratio, reliability /
  calibration curves, rolling-window and walk-forward validation.
- **Excel integration** — `=MERTON_DD(equity, σE, debt, rf, T)` and friends,
  available in Excel Web, Excel Mac (M365), and Excel Windows via xlwings Server.
- **Climate stress** — composable `Scenario` framework with packaged NGFS Phase V
  (2024) scenarios (`net_zero_2050`, `delayed_transition`, `current_policies`,
  `fragmented_world`); `ClimateOverlay` wraps any structural model with
  carbon-price paths and sectoral PD multipliers.
- **OpenTelemetry observability** — opt-in via `merton.obs.enable(...)`; pipes
  spans to any OTLP-compatible backend (Datadog, Honeycomb, Tempo, …).
- **Modern Python** — type hints, Pydantic settings, structured logging,
  Apache-2.0 license, cross-platform wheels for Python 3.11-3.14 (incl. free-threaded).

## Quickstart

```bash
uv pip install merton          # or: pip install merton
```

```python
from merton import Firm, fit

firm = Firm(
    equity=100_000_000,        # $100M market cap
    debt_short=20_000_000,
    debt_long=30_000_000,
    equity_vol=0.30,
    rf=0.045,
    horizon=1.0,
)

result = fit(firm, method="vassalou_xing")
print(result.summary())
# MertonResult
#   distance_to_default : 3.142
#   probability_of_default : 0.000839
#   asset_value : 148.6M
#   asset_vol : 0.207
#   implied_spread (LGD=0.6) : 5.0 bps
```

## Excel integration

```bash
merton excel install
merton excel server start --port 8000
```

Then in any Excel workbook (Web / Mac / Windows):

```
=MERTON_DD(B2, B3, B4+B5, B6, B7)        # distance to default
=MERTON_PD(B2, B3, B4+B5, B6, B7)        # probability of default
=MERTON_SPREAD(B2, B3, B4+B5, B6, B7, 0.6)
```

See [the Excel docs](https://merton.readthedocs.io/en/latest/excel/installation.html) for the full reference.

## Performance

- Single-firm fit: <50 ms
- 10 000-firm × 10-year daily panel: <60 s on 8 cores (Numba backend)
- 100 000-sim portfolio VaR: <30 s with GPU (CuPy)

## Documentation

Full docs at <https://merton.readthedocs.io> including:

- Theory deep-dives (Merton 1974, KMV, Black-Cox, Geske, …)
- Executable tutorials (AAPL time series, panel backtest, portfolio VaR,
  climate stress test, GPU acceleration, Excel integration)
- API reference
- Performance benchmarks and backend-selection guide

## Installation matrix

| Goal | Command |
|---|---|
| Minimum (CPU NumPy) | `pip install merton` |
| Numba JIT (default fast path) | `pip install merton` (Numba is a hard dep) |
| GPU acceleration | `pip install "merton[gpu]"` (requires CUDA 12) |
| JAX autodiff calibration | `pip install "merton[jax]"` |
| Apple Silicon GPU | `pip install "merton[mlx]"` |
| Excel integration | `pip install "merton[excel]"` |
| Visualization (matplotlib + plotly) | `pip install "merton[viz]"` |
| Bayesian MCMC calibration | `pip install "merton[mcmc]"` |
| OpenTelemetry tracing | `pip install "merton[obs]"` |
| Everything | `pip install "merton[all]"` |

## License

Apache-2.0 — see [LICENSE](LICENSE).

## Citing

If you use `merton` in academic work, please cite via the
[CITATION.cff](CITATION.cff) file or the package's Zenodo DOI (assigned on first
tagged release).
