ModelRisk

ModelRisk: Run the model audit against the workbook. Each rule's detector lives in modelrisk_mcp.audit.rules; the rule set is editable in data/audit_rules.yaml. Returns an AuditReport with severity-tagged findings (error/warning/info) and suggested fixes.

ModelRisk: Backtest a simulation output against realised actuals — does the model's predicted distribution match what actually happened? Reports the Probability Integral Transform (PIT, ~0.5 mean and uniform if calibrated), the empirical coverage of central prediction intervals (e.g. ~90% of actuals should fall in the 90% interval), and bias. Pass the historical `actuals` you want to validate against. Reads the output's per-iteration samples — run the simulation first.

ModelRisk: Build a single-sheet drivers report — a sensitivity analysis presented for a decision-maker. Drops onto a new sheet: title band; auto-generated KEY FINDINGS in plain English ('The dominant driver of NPV is widget cost, r = -0.65; higher widget cost lowers NPV'); a prominent tornado chart; a driver-ranking table with correlation + |r| + approximate variance share; a HOW TO READ THIS CHART panel for stakeholders who don't know what Spearman correlation means; and tiered RECOMMENDED ACTIONS (focus / monitor / deprioritise) grouping inputs by strength. Use this when the user asks for an uncertainty-drivers report rather than the broader executive dashboard.

ModelRisk: Build a single-sheet executive report for a decision-maker. Drops a curated dashboard onto a new sheet with: title band, headline numbers (mean / P5 / P50 / P95 / stdev — colored by volatility), histogram + cumulative chart of the primary output, tornado of top N sensitivity drivers, a stats table for the primary plus any secondary outputs, and auto-generated risk callouts framed in plain English ('90% confident X lands between A and B', 'tail risk Y% above mean', 'primary driver is Z'). Idempotent — re-running replaces the sheet. Use this when the user asks for a decision-maker-facing summary rather than raw stats.

ModelRisk: Turn a deterministic workbook into a simulation-ready Monte Carlo model in one atomic, reversible pass. Given the output cells to track and the uncertain inputs to add (each with a Vose distribution family + parameters you choose from the brief), it wraps the outputs with VoseOutput, replaces the input cells with VoseInput-wrapped distributions, optionally runs a validating simulation, and returns the headline percentiles. Every write goes through the audit-logged safe-write path and is tracked in a change-set: if any step fails, the ENTIRE build is rolled back so the workbook is never left half-converted. Defaults to dry_run=True. This end-to-end build+simulate is exactly what an advisory agent cannot do.

ModelRisk: Close an open workbook by file name. By DEFAULT unsaved changes are DISCARDED (save=False) — pass save=True to write them first. Returns the closed name and the workbooks still open. Raises if the named workbook isn't open.

ModelRisk: Compare two simulation outputs head-to-head from their per-iteration samples — mean/stdev/percentile differences, P(A > B), and first- and second-order stochastic dominance (under the convention that larger outcomes are preferred). First-order dominance means one option is better at every probability level; second-order adds risk-aversion. Use it to decide between strategies. Run a simulation that records both outputs first.

ModelRisk: Compute the rank-order (Spearman) correlation matrix of a data range via VoseCorrMatrix, and its nearest valid (positive-semidefinite) form via VoseValidCorrmat. Use this to turn historical data into the correlation matrix you feed to create_copula for correlated inputs. Variables are columns by default (set `data_in_rows=True` if each row is a variable). Read-only: runs on a transient scratch sheet that is always deleted.

ModelRisk: Analytic distribution calculator — compute a property of a distribution WITHOUT running a simulation. Give a `family` (e.g. 'Normal', 'Lognormal', 'PERT') and its `parameters`, OR point at an `object_cell` that already holds a Vose distribution object (e.g. a fitted distribution). `metric` is one of: 'pdf' (density f(x)), 'cdf' (P(X<=x)), 'exceedance' (P(X>x)), 'quantile' (the x at cumulative probability u), 'mean', 'stdev', 'variance', 'skewness', 'kurtosis', 'cov', or 'summary' (all moments + a percentile ladder in one call). `at` is x for pdf/cdf/exceedance and u (0-1) for quantile. Exact, read-only: nothing is written and no simulation is run.

ModelRisk: Build a frequency-severity aggregate using the chosen `method` — 'FFT' (Fast Fourier Transform) or 'Panjer' (Panjer recursion) for the fast analytic methods, or 'MC' for Monte Carlo. frequency_object_cell and severity_object_cell are references to distribution-object cells (built with Vose<Family>Object). FFT and Panjer support `as_object=True`, which writes the ...Object form whose mean and percentiles can be read directly with compute_distribution / get_tail_risk — the aggregate loss distribution WITHOUT running a simulation. Method-specific options: `density` (FFT), `intervals` / `max_p` (Panjer), `min_limit` / `max_limit` / `distribution_shift` (MC). For plain MC sampling, create_aggregate_mc is the dedicated shortcut.

ModelRisk: Build a VoseAggregateMC(n, distribution, ...) formula that simulates the aggregate of a (possibly random) number n of i.i.d. severity draws. n and distribution are cell references — n points at a frequency cell, distribution at a severity object cell (built with a Vose<Family>Object function).

ModelRisk: Render the ascending cumulative-probability curve (CDF) of one output's simulation result distribution as a new sheet in the workbook. The sheet has a binned data table plus a native Excel line chart of cumulative probability (0-100%) against the output value — the 'what's the chance the output is below X' view. Requires a completed simulation (reads samples from the active .vmrs). Idempotent — a sheet with the target name is replaced.

ModelRisk: Build a copula formula (e.g. VoseCopulaMultiNormal) that produces a correlated u-array for downstream distribution calls. Copula tools are exempt from the bulk-write guard.

ModelRisk: Render a histogram of one output's simulation result distribution as a new sheet in the workbook. The sheet has a binned data table (bin centre / frequency / cumulative %) plus a native Excel chart: frequency columns with the cumulative-probability curve overlaid on a secondary % axis and the central-80% (P10-P90) band highlighted — the same view as ModelRisk's Results Viewer, persisted into the workbook. Requires a completed simulation (reads samples from the active .vmrs). Idempotent — a sheet with the target name is replaced.

ModelRisk: Build a VoseRiskEvent(probability, impact_object) formula. The impact_function_name must be a distribution-object function (category 'object') — typically a Vose<Family>Object variant.

ModelRisk: Build a time-series formula (VoseTimeGBM, VoseTimeAR1, etc.) and write it into the target_range. Time-series tools are exempt from the >50-cell bulk-write guard because the dimension of the time series is the whole point.

ModelRisk: Render a tornado chart of input sensitivity for a single output as a new sheet in the workbook. The sheet has a sorted data table (Spearman rank correlation + regression coefficient per input) plus a native Excel BarClustered chart with the largest-magnitude input at the top. Idempotent — if a sheet with the target name already exists, it's replaced. Useful when the user wants the visualization persisted in the workbook, not just returned over MCP.

ModelRisk: Split an output's uncertainty into EPISTEMIC (parameter / knowledge uncertainty — reducible with more data) and ALEATORY (natural variability — irreducible), via the law of total variance. ModelRisk has no two-dimensional-simulation worksheet function, so this approximates it from two runs you provide as two outputs: `total_output` from a full run (everything varying), and `conditional_output` from a run with the epistemic/parameter inputs FROZEN at point estimates (only natural variability left). Epistemic variance = total - aleatory. Tells you whether collecting more data (cuts epistemic) or hedging variability (aleatory) is the lever.

ModelRisk: One-call workbook health check. Returns everything an MCP client typically wants at the start of a session: whether Excel is reachable, whether the ModelRisk SDK is activated, the active workbook's name + sheets, counts of inputs / outputs / distributions, whether a sibling `.vmrs` exists and when it was last modified, and the audit-log location. Use this as the first call instead of orchestrating 4-5 individual reading tools.

ModelRisk: Discover candidate input cells — numeric cells referenced by formulas — and rank them by how likely they are to be uncertain model inputs (vs. constants like 12 months per year). The ranking weighs reference count and number magnitude. Pair with propose_distributions_for_inputs.

ModelRisk: Heuristic discovery of cells that look like deterministic numeric inputs — i.e. a plain number, referenced by at least one formula. These are candidates for replacing with a distribution + VoseInput wrapper.

ModelRisk: Fit BOTH the marginal distributions and the copula dependence from a data block, then wire the whole correlated, simulation-ready model into the workbook in one reversible pass. For each variable column it fits+ranks the best marginal (AIC/SIC/HQIC); across the columns it fits the best copula (fit_copula_to_data) and writes the correlated-U block at `copula_anchor`; each marginal is wired to its copula U so the inputs are dependent, not independent — capturing the tail co-movement a single correlation coefficient discards. Optionally runs a validating simulation. Defaults to dry_run=True (returns the exact planned formulas without writing). On any mid-build failure the whole change-set is rolled back. This is the data→model step no advisory agent can perform.

ModelRisk: Fit several distribution families to a data range and rank them by goodness of fit. For each family it fits Vose<Family>FitObject and scores it with ModelRisk's information criteria — AIC, SIC (Schwarz/BIC) and HQIC — then ranks ascending (lower = better) by `criterion`. Families with no fit function, or that can't fit the data, are returned under `skipped` with a reason. Use this instead of guessing a single family for fit_distribution_to_data. Runs on a transient scratch sheet that is always deleted; the data is not modified.

ModelRisk: Fit parametric copulas to a multi-column data range and rank them by goodness of fit — the DEPENDENCE STRUCTURE fitted from data, not merely constructed. Tries Normal, T, Clayton, Frank and Gumbel families (Vose<Family>FitObject), scores each with AIC / SIC / HQIC, and reports the winner plus its tail-dependence character (lower = crash-together, upper = boom-together, both = T, none = Normal/Frank) — the joint-tail risk a single correlation coefficient throws away. Runs on a transient scratch sheet that is always deleted; the data is not modified. Pair with fit_all_data_and_wire to insert the fitted copula into the model.

ModelRisk: Fit a distribution family to a data range and write the result. 'family' is e.g. 'Normal', 'Lognormal', 'Beta', 'Gamma', 'Weibull' — the tool maps it to the catalogue function (Vose<Family>Fit). Set uncertainty=True (the default) to include parameter uncertainty in the fitted distribution.

ModelRisk: Fit an extreme-value / Generalised-Pareto tail to data and read its risk. `family` is 'GPD' (peaks-over-threshold, the standard tail model), 'GEV' (block maxima), 'ExtValueMax', or 'ExtValueMin'. For GPD peaks-over-threshold, pass the range of exceedances above your threshold as `data_range`. Writes a Vose<Family>FitObject (dry_run previews) and returns the fitted tail's mean and high percentiles (P95 / P99 / P99.5 / P99.9) computed analytically — the tail risk without a simulation. Feed the written object cell to compute_distribution / get_tail_risk for more.

ModelRisk: Fit TIME-SERIES models to a historical data range and rank them by goodness of fit — GBM (plus mean-reverting / jump-diffusion / seasonal variants), AR1/AR2, MA1/MA2, ARMA, ARCH/GARCH/EGARCH. Each family's VoseTime<Family>FitObject is scored with AIC / SIC / HQIC on a transient scratch sheet (nothing in the workbook is modified by the ranking). Optionally pass `target_range` (+ dry_run=False) to write the best model's projection — a VoseTime<Family>Fit(...) ARRAY formula, one period per cell, CSE-entered — so each simulated path carries the fitted dynamics (autocorrelation, volatility clustering) period to period. Note: unlike distribution fitting, parameter uncertainty is not supported here.

ModelRisk: Generate an executive-audience summary of the most recent simulation results for a workbook. Returns markdown ready to paste into a deck/report — covers deterministic vs P50 vs mean comparisons, P80 contingency, and the top sensitivity drivers.

ModelRisk: Get the name and path of the active workbook.

ModelRisk: Read a single cell's formula, value, and number format.

ModelRisk: Pearson and Spearman rank correlation between the named simulation inputs and outputs. Computed from the per-iteration samples ModelRisk records. Pass a name list to restrict; otherwise all variables are included.

ModelRisk: Return raw per-iteration sample values for a single output or input. Useful for custom histograms, arbitrary percentiles, downstream analysis. Caps at 10 000 samples by default to keep the MCP response small; raise `max_n` if you need more (a 100 000-iteration sim returns ~100 KB of JSON at max_n=100000).

ModelRisk: Tornado / sensitivity ranking for a single output. Returns each input ranked by its Spearman rank correlation with the output, plus the standardised regression coefficient.

ModelRisk: Read simulation result statistics for the workbook's outputs. Returns per-output mean, stdev, variance, skewness, kurtosis, min, max, and P5/P10/P25/P50/P75/P90/P95 percentiles. Requires a simulation to have been run; pass output_names to filter.

ModelRisk: Tail-risk profile of a simulation output from its per-iteration samples — Value-at-Risk (VaR) and Conditional VaR / expected shortfall (CVaR) at each confidence level, plus optional threshold probabilities P(X>t) / P(X<=t). `tail='upper'` (default) treats large values as the loss (e.g. cost, claims); `tail='lower'` treats small values as the loss (e.g. NPV, profit). VaR is the alpha-quantile; CVaR is the mean of the worst (1-alpha) tail beyond it. Reads the samples ModelRisk recorded in the .vmrs — run a simulation first.

ModelRisk: Aggregated summary of a workbook — sheet names plus counts of VoseInput, VoseOutput, distribution, formula, and numeric cells. One-shot alternative to running the individual list tools.

ModelRisk: Write a Vose distribution formula (e.g. =VoseModPERT(...)) into a cell. Validates the function name against the ModelRisk catalogue. Defaults to dry_run=True — Claude must explicitly pass dry_run=False to commit.

ModelRisk: List every cell containing a Vose distribution / aggregate / copula / time-series / fitting function. Includes flags for whether each cell is also wrapped with VoseInput or VoseOutput. Optional `sheet` restricts the scan to one sheet.

ModelRisk: List every cell wrapped with VoseInput() in the workbook. Returns each cell's reference, the input name, the full formula, and the current calculated value.

ModelRisk: List every cell wrapped with VoseOutput() in the workbook.

ModelRisk: List all Excel workbooks currently open.

ModelRisk: List every variable in the active simulation results (`.vmrs`) that's also declared as a VoseInput or VoseOutput in the workbook. Each entry: `{name, kind, var_id, iterations}`. Use this before `get_samples` or `read_vmrs` when you don't already know which outputs / inputs exist in the file.

ModelRisk: Open a workbook (.xlsx/.xlsm) from disk in the running Excel so the other tools can act on it. Pass an absolute file path. If a workbook with the same file name is already open, returns that one (Excel won't open two with the same name). Requires Excel running.

ModelRisk: One-call blueprint for turning a deterministic workbook into a Monte Carlo risk model. Reports what's already there (declared outputs, existing distributions), the ranked hard-coded cells that look like uncertain inputs, and an ordered, state-aware checklist of next actions (wrap outputs, fit/propose distributions, correlate, audit, simulate, interpret). Read-only — it plans, it doesn't modify. Run this first when asked to 'add uncertainty' or 'make this a risk model'.

ModelRisk: Propose distribution families for a list of uncertain inputs. Each input gets a ranked list of recommendations from the methodology-grounded selection guide. The tool does NOT write to Excel — it returns suggestions for the LLM to walk through with the user before committing via replace_constant_with_distribution.

ModelRisk: Read a contiguous range as a 2D array of values and formulas. Use ranges like 'A1:C10'.