RiskPY

A risk and actuarial engine: a C++ core with no Python dependencies, and a modelling layer in readable Python that covers Monte Carlo with dependence, life contingencies, claims reserving, yield curves and short-rate models, credit risk, option pricing, and twenty-two charts — with a verification suite that checks every identity the library claims on every push.

📖 Documentation → slimboi34.github.io/RiskPY

pip install open-riskpy            # core, zero dependencies
pip install "open-riskpy[sim]"     # + NumPy: simulation and the numeric layers
pip install "open-riskpy[viz]"     # + Matplotlib: the charts

from riskpy.mc import Model, Poisson, LogNormal, Normal

model = Model(
    claim_count = Poisson(mean=140),
    severity    = LogNormal.from_moments(mean=18_000, sd=42_000),
    inflation   = Normal(mean=0.043, sd=0.012),
)
model.correlate("claim_count", "inflation", 0.3)

@model.formula
def annual_loss(claim_count, severity, inflation):
    return claim_count * severity * (1 + inflation)

result = model.run(200_000, seed=42, sampling="lhs")
print(result.summary())          # mean, VaR, TVaR at every level
result.plot("dashboard")         # distribution, exceedance, convergence, tornado

v0.5.2 — a pickled error keeps its value and notes across processes, riskpy-tools trace no longer crashes on a broken trace file, and an overflowing aggregate_loss says which argument to fix. No result changes.

v0.5.1 — fixes from black-box testing 0.5.0: parametric value_at_risk reports the normal expected shortfall (it returned the historical one), bornhuetter_ferguson refuses a loss ratio typed as a percentage, errors name the tool's own argument, the wheels no longer drop OpenXLSX's headers and libraries into site-packages, and macOS x86_64 wheels ship again. See RELEASE_NOTES.md.

v0.5.0 — RiskPY tells you (and your agent) exactly what went wrong. Every error has a stable code, names the parameter and says how to fix it (riskpy-explain RP105); the tools and the MCP server return {"error": {code, message, param, hint}} instead of tracebacks and refuse percentages where decimals belong (r=5, sigma=20) rather than compute a confident wrong answer. riskpy-doctor checks an installation end to end, a call trace shows what an agent has been doing (riskpy-tools trace, riskpy_status), and eleven more verified calculators are tools (27 in all). On a scripted set of 19 agent mistakes the share of failures that come back with a code, the parameter, a fix and structured JSON goes from 4% (0.4.0) to 100%. Ships the unpublished 0.4.1 security fixes. No numerical result changes. See RELEASE_NOTES.md.

v0.4.0 — for AI agents: sixteen verified calculators as tools with JSON schemas (riskpy-tools, riskpy.tools.call), an MCP server (riskpy-mcp, pip install "open-riskpy[mcp]") so Claude Code and friends can price, reserve and simulate with numbers the verification suite stands behind, and riskpy-context, a description of the library generated from the installed package for the model about to use it. It builds on v0.3.x: four fields of risk (life, reserving, rates, credit), a rewritten Monte Carlo engine, twenty-two charts and the verification suite. See RELEASE_NOTES.md.

What is in the box

Every layer is imported lazily, so import riskpy on a machine with nothing but the wheel installed works and gives you the compiled core.

A taste of each

from riskpy import life, reserving, rates, credit, quant, viz

# Life: the textbook's own numbers
sult = life.LifeTable.sult()
life.whole_life_annuity_due(sult, 40, i=0.05)        # ä_40 = 18.457757 (AMLCR Table D.3)
life.net_premium_reserve(sult, 40, t=10, i=0.05, kind="endowment", n=20)

# Reserving: the GenIns triangle, with uncertainty
tri = reserving.genins()
mack = reserving.mack_chain_ladder(tri)
mack.total_reserve, mack.total_se                     # 18,680,856 ± 2,447,095
boot = reserving.bootstrap_chain_ladder(tri, n=5000, seed=1)
viz.exceedance(boot.result())                         # a reserve distribution, charted

# Rates: a bond on a bootstrapped curve
curve = rates.YieldCurve.bootstrap([0.020, 0.025, 0.028, 0.030], [1, 2, 3, 4])
bond = rates.Bond(face=100, coupon=0.05, maturity=4, frequency=2)
bond.z_spread(bond.price(0.045), curve)

# Credit: Basel capital and a correlated portfolio
credit.basel_irb_capital(pd=0.01, lgd=0.45, ead=1e6).risk_weight    # 92.32%
pds, lgds, eads = [0.01] * 500, [0.45] * 500, [1e6] * 500             # 500 identical loans
credit.credit_portfolio_loss(pds, lgds, eads, rho=0.2, trials=100_000, seed=1).var(0.999)

# Quant: still pure Python for the closed forms
quant.black_scholes(S=100, K=100, T=1, r=0.05, sigma=0.2)           # 10.4506
quant.heston_price(S=100, K=100, T=1, r=0.03, v0=0.04, kappa=2, theta=0.04, xi=0.5, rho=-0.7)

For AI agents

riskpy-tools                         # 27 verified calculators as tools, with JSON schemas
riskpy-tools call black_scholes '{"S": 100, "K": 100, "T": 1, "r": 0.05, "sigma": 0.2}'   # 10.4506
riskpy-mcp                           # the same tools over MCP  (pip install "open-riskpy[mcp]")
riskpy-context                       # the library described for the model about to use it
riskpy-doctor                        # is this installation healthy? (--json; exit 1 on a failure)
riskpy-explain RP104                 # what an error code means and how to fix the call
riskpy-tools trace                   # the recent tool calls, with durations and error codes

A call that goes wrong comes back as data an agent can act on, never a traceback:

$ riskpy-tools call black_scholes '{"S": 100, "K": 100, "T": 1, "r": 5, "sigma": 0.2}'
{"error": {"code": "RP104", "param": "r",
           "message": "r = 5 looks like a percentage: rates are decimals, so |r| must be at most 1",
           "hint": "Divide by 100 — 5% is 0.05.", "docs": "https://slimboi34.github.io/RiskPY/errors/#rp104"}}

from riskpy import tools; tools.manifest() is the list as data and tools.call(name, {...}) runs one; every tool wraps a public function the verification suite checks, takes plain numbers (rates as decimals, times in years) and returns JSON. riskpy-mcp --config prints the client configuration for Claude Code, Claude Desktop or Cursor. riskpy-context generates the conventions that bite, every module's public signatures and the tool list from the installed package, so it cannot go stale. Over MCP, riskpy_status, riskpy_doctor and riskpy_explain let the agent see its recent calls, check the installation and look up a code or a tool's formula. See the docs, diagnostics and the error codes.

Verification

riskpy-verify              # 111 checks (125 with SciPy), ~1 second
riskpy-verify --bench      # plus timings
riskpy-verify -m life      # one module; a module whose extra is missing is skipped, not failed

A test suite says the code does what it did yesterday. The verification suite says it is right: put–call parity, A_x = 1 − d·ä_x, Mack's standard error on the reference triangle, the Basel risk-weight table, Φ⁻¹(Φ(x)) = x, the contrast ratio of every palette colour — each computed and compared to a source the library had no hand in. It runs in CI on every push, nightly with the SciPy oracle, and the docs site publishes the latest report.

Install (developers)

git clone https://github.com/slimboi34/RiskPY.git
cd RiskPY
make install    # pip install -e ".[dev]"
make test       # pytest — 522 test cases
make verify     # the verification suite

Without Make:

pip install -e ".[dev]"
pytest tests/
python -m riskpy.verify

From source you need a C++17 compiler and CMake ≥ 3.15 (pulled automatically by the build backend when missing). Pre-built wheels ship for Python 3.10–3.14 on Linux, macOS and Windows.

The compiled core

from riskpy import FactorModel, FourierTransform, MonteCarloSimulator, LossTriangle

model = FactorModel(initial_base_rate=1000.0)
model.add_multiplier("state", "FL", 3.0)
model.add_numeric_band_multiplier("age", 16, 25, 2.0)
model.calculate({"state": "FL", "age": 19.0})          # 6000.0

# Severity always 1 → aggregate is Poisson(λ), with no sampling error at all
pmf = FourierTransform.compound_poisson_pmf([0.0, 1.0], expected_frequency=2.0, grid_size=64)

sim = MonteCarloSimulator(trials=200_000, seed=7)
losses = sim.simulate_aggregate_loss(5.0, 8.0, 0.5)

import riskpy is headless-safe; the Tkinter GUI (UnderwritingApp) loads only when you use it.

Releasing (maintainers)

# After merging to main and bumping version in pyproject.toml:
make release   # tags vX.Y.Z and pushes — that is the whole release

The tag push checks the tag against the version, builds the sdist and wheels and smoke-tests their imports, uploads to PyPI via Trusted Publishing, and cuts the GitHub Release with artifacts attached. Details in docs/PUBLISHING.md.

License

RiskPY is Copyright © 2026 Joshua Harty and is released under the MIT License — see LICENSE. Free for personal and commercial use, modification and redistribution; keep the copyright and permission notice with any copy.

• GitHub: github.com/slimboi34/RiskPY
• PyPI: pypi.org/project/open-riskpy