For AI agents¶
An agent that can call functions needs three things from a library: a list of what it may call, a schema for each call, and results it can pass on as data. RiskPY provides all three, generated from the calculators' own signatures and docstrings, plus a description of the library written for the model that is about to use it. Since 0.5.0 it also tells the agent exactly what went wrong when a call fails — a stable error code, the parameter, the fix, as JSON — and lets it look at what has been happening (Diagnostics). Since 0.7.0 it can drive any calculator through a stress test with one call, the MCP server offers resources and prompts as well as tools, and every call can be recorded to a tamper-evident ledger (The audit ledger).
pip install open-riskpy # the core: most tools run with no dependencies
pip install "open-riskpy[sim]" # + NumPy: the claims-triangle, VaR and capital-allocation tools
pip install "open-riskpy[mcp]" # + the MCP SDK: riskpy-mcp
The tools¶
riskpy-tools # the list
riskpy-tools --json # the manifest: name, description, input schema, what it needs
riskpy-tools call black_scholes '{"S": 100, "K": 100, "T": 1, "r": 0.05, "sigma": 0.2}' # 10.4506
riskpy-tools schema aggregate_loss
riskpy-tools trace # recent calls, durations, error codes
riskpy-doctor # is this installation healthy?
riskpy-explain RP104 # what an error code means
riskpy-audit replay run.jsonl # recompute every call in an audit ledger (RISKPY_AUDIT_FILE writes one)
from riskpy import tools
tools.manifest() # a list of dicts, one per tool
tools.call("basel_irb_capital", {"pd": 0.01, "lgd": 0.45, "ead": 1e6})["risk_weight"] # 0.9232
tools.call("black_scholes", {"S": 100, "K": 100, "T": 1, "r": 5, "sigma": 0.2}, errors="return")
# {"error": {"code": "RP104", "param": "r", "message": "r = 5 looks like a percentage: ...",
# "hint": "Divide by 100 — 5% is 0.05.", "docs": "..."}}
| tool | what it does |
|---|---|
black_scholes, option_greeks, implied_vol |
European options, pure Python (black_scholes takes explain: true for d1, d2 and the convention; option_greeks gives vega and rho per percentage point and theta per calendar day) |
value_at_risk |
historical or parametric VaR and expected shortfall of a return series (NumPy) — new in 0.5.0 |
bond_analytics |
price, Macaulay and modified duration, convexity, DV01 at a yield |
convert_rate, bootstrap_yield_curve, short_rate_zero_bond |
compounding conventions, a zero curve from par yields, Vasicek / CIR bond prices — new in 0.5.0 |
basel_irb_capital, expected_loss, merton, cds_par_spread |
credit risk |
hazard_from_spread, vasicek_loss_quantile |
the credit triangle; the ASRF portfolio loss quantile — new in 0.5.0 |
annuity_certain, life_annuity_due, life_insurance, net_premium_reserve |
life contingencies on the AMLCR standard table |
term_insurance, endowment_insurance, temporary_annuity_due, life_premium |
n-year contracts and net premiums — new in 0.5.0 |
aggregate_loss |
a year of claims simulated by the compiled core: Poisson frequency, lognormal severity, VaR and TVaR out |
chain_ladder, mack_chain_ladder, bornhuetter_ferguson |
claims triangles (need NumPy; BF new in 0.5.0) |
capital_aggregate, capital_allocation |
diversified capital from standalone figures and a correlation matrix; simulated lines joined by a copula with TVaR or VaR allocated to them (Economic capital; allocation needs NumPy) — new in 0.7.0 |
copula_dependence, nearest_correlation |
what a copula implies (Kendall's tau, tail dependence, joint exceedance); repair a correlation matrix that is not positive semi-definite (NumPy) — new in 0.7.0 |
sensitivity, scenario_table |
bump-and-revalue any calculator: derivatives and elasticities of every output; any calculator under named what-ifs (Stress and scenario testing) — new in 0.7.0 |
verify |
the verification suite, as data |
riskpy_status, riskpy_doctor, riskpy_explain |
introspection: recent calls and error counts, the installation check, an error code or a tool's formula and conventions — new in 0.5.0 |
riskpy_audit |
introspection: whether calls are being recorded to the audit ledger, the head digest to quote, and optionally a replay — new in 0.7.0 |
Every tool is a thin wrapper over a public function that the verification suite
checks. Arguments are plain numbers, strings and lists: rates as decimals, times in years,
probability levels as decimals. Results are JSON. The wrappers hide the conventions that
bite — aggregate_loss takes a severity mean and standard deviation on the money scale
and converts to the lognormal parameters itself, so an agent cannot make the commonest
severity mistake there is. A tool whose extra is not installed is reported as
available: false with the pip install line, and calling it raises ToolUnavailable
(code RP201) saying the same.
Arguments are checked before anything runs, on every path (tools.call, the CLI, MCP, a
direct Python call): numbers must be finite numbers (no NaN, Infinity, true or "100"),
whole numbers whole, and the work one call can ask for is bounded — aggregate_loss takes at
most 1,000,000 trials and 10⁸ simulated claims (trials × expected frequency),
bond_analytics and cds_par_spread at most 100,000 payment periods (maturity × frequency),
the triangle tools at most 300 × 300, the capital tools at most 100 risks and 5 × 10⁶ simulated cells
(trials × lines: about 2 s and 250 MB at the limit), scenario_table at most 100 scenarios. Strings, tool names, argument names and
scenario labels are at most 200 characters, and an object argument nests at most 32 levels deep. The
limits are in riskpy.tools.LIMITS; a call over one fails at once with code RP405 and a message naming
it, and never echoes the oversized value back. The tools also refuse percentages where
decimals belong — a rate above 100% (RP104), a volatility above 500% (RP105), an LGD above 1
(RP103), an expected loss ratio above 500% (RP104) — because the library would compute a confident wrong answer from them
(riskpy.tools.PLAUSIBLE). Results never contain NaN or Infinity, so they are strict JSON: a
number that overflowed is refused with RP304, never returned as null. A null number is a value
that is undefined by construction, and a note beside it says why: merton's
distance_to_default when σ√T is zero (with "deterministic": true), mack_chain_ladder's
total_cv when the total reserve is 0, black_scholes' explain.d1 / d2 when σ√T is too small
for them to be finite.
When a call fails¶
Every refusal carries a stable code, the parameter and a hint. tools.call(name, args,
errors="return"), riskpy-tools call and riskpy-mcp all return it as
{"error": {"code", "message", "param", "hint", "docs"}} — no tracebacks — and the default
errors="raise" raises it as the ValueError / TypeError / KeyError earlier versions raised,
with .code, .param, .hint and .to_dict(). An unknown argument gets a suggestion (vol →
sigma), a misspelt tool a "did you mean". The error codes page lists them all;
Diagnostics covers riskpy-doctor and the call trace.
The manifest's input_schema is JSON Schema, so the same list drives Anthropic tool use,
OpenAI function calling, or any framework that takes schemas.
Over MCP¶
pip install "open-riskpy[mcp]"
riskpy-mcp --config # the client configuration, and the `claude mcp add` line
claude mcp add riskpy -- riskpy-mcp # Claude Code
riskpy-mcp serves every available tool on stdio under its own name, with the schema
derived from its signature (every parameter described) and the description from its
docstring, so Claude Code, Claude Desktop, Cursor and any other MCP client can price an
option, size Basel capital or simulate a year of claims with numbers the verification suite
stands behind. Calls run through tools.call, so a string sent where a number belongs is
refused (RP404) rather than silently coerced, and every failure is a JSON error object the
agent can act on. riskpy_status, riskpy_doctor and riskpy_explain let it look at the
recent calls, the installation and the meaning of a code without leaving the session.
Tools that drive other tools¶
sensitivity and scenario_table take the name of another calculator and its arguments as an
object:
from riskpy import tools
tools.call("sensitivity", {"tool": "bond_analytics", "parameter": "ytm",
"arguments": {"face": 100, "coupon": 0.05, "maturity": 10, "ytm": 0.04}})
# outputs.price: base 108.1757, derivative −857.02 per 1.00 of yield (−0.0857 per basis point),
# second_derivative 8164.3
The inner call is checked exactly as a direct call is, so a percentage where a decimal belongs is still refused with the same code. An agent no longer needs three calls and its own arithmetic to get a duration or a delta, and cannot get the finite difference wrong.
One meta-tool call is still one tool call. sensitivity runs the calculator up to four times and
scenario_table once per scenario plus the base, and all those runs together may ask for no more
work than one call of the calculator at its limit: 100 scenarios of a one-million-trial
simulation are refused before anything runs (RP405), with a message naming the largest run.
verify cannot be driven. A scenario table still running after LIMITS["meta_seconds"] (20 s)
returns the scenarios it finished and lists the rest under not_run, each with RP405. Over MCP, a
client that cancels the request stops the work at the next gap between runs (RP408 in the trace).
For a simulation (aggregate_loss, capital_allocation) the default bump is 1% of the value —
1% of its distance to 0 or 1 for a confidence level — rather than the 0.0001 × max(1, |value|) a
closed form gets: a smaller bump measures sampling noise (a 0.01% bump of the claim frequency gave
a derivative of −12,566 where the true one is 1,000). A simulated derivative still carries some
noise; repeat it with a different bump or more trials before relying on it.
Resources and prompts¶
Besides tools, riskpy-mcp serves reference text as MCP resources, which a client can
attach to the conversation without a tool call:
| resource | what it is |
|---|---|
riskpy://context |
the context pack (Markdown) |
riskpy://conventions |
the conventions that bite (Markdown) |
riskpy://errors |
the error catalogue (JSON) |
riskpy://tools |
the tool manifest (JSON) |
riskpy://audit |
the audit ledger's status and head digest (JSON) |
riskpy://explain/{topic} |
an error code or a tool explained (JSON) |
and prompts, which are step-by-step procedures for jobs that take several tools in the right order:
| prompt | arguments | what it walks through |
|---|---|---|
capital_model |
lines, level |
repair the correlation matrix, aggregate, allocate with Euler contributions, compare copulas |
reserve_review |
triangle |
chain ladder, Mack standard errors, Bornhuetter–Ferguson, sensitivity to the tail factor |
stress_test |
tool, base_case |
sensitivities to each input, named scenarios, where the linear estimate breaks down |
audit_trail |
— | the ledger head, the chain check and the replay for this conversation's numbers |
Every prompt ends by asking for the ledger head. The same text is available without MCP:
from riskpy import mcp_server
mcp_server.read_resource("riskpy://conventions")
mcp_server.render_prompt("capital_model", lines="motor, property, liability", level="0.995")
Recording a session¶
Every calculator call the agent makes is then written in full to a hash-chained ledger.
riskpy_audit gives the agent the head digest to quote, and riskpy-audit replay
session.jsonl lets anyone recompute the session afterwards. See The audit ledger.
The server opens the ledger when it starts and exits with an RP505 message if it cannot (a
mistyped folder would otherwise record nothing and say nothing); riskpy-tools call warns on
stderr when a call could not be recorded.
The context pack¶
riskpy-context # Markdown: install, conventions that bite, every module's
# public functions with signatures, the tools, verification
riskpy-context --json # the same as data
riskpy-context -o AGENTS.md # write it for the agent working in your project
It is generated from the installed package, so the signatures are the ones that will run:
functions and class constructors with their signatures, each class's own summary (not one
inherited from a base class) and all its public methods, and a worked example of a model run
with a copula, allocated and stressed.
The "conventions that bite" section is the part to read first: rates are decimals, i is
effective annual while r is continuous, LogNormal(mu, sigma) takes the underlying
normal's parameters, seeds make runs reproducible, a copula's correlation is not a Spearman
correlation, losses are positive, and riskpy-verify is how to check rather than trust.