Add fit_copula_to_data, reverse_stress_test, fit_all_data_and_wire, build_model_from_brief (0.3.8)

Four functional tools that widen the capability gap vs an advisory agent —
each needs to run the engine and/or hold the per-iteration joint sample matrix:

- fit_copula_to_data (analysis): fit Normal/T/Clayton/Frank/Gumbel copulas
  to a data block, rank by AIC/SIC/HQIC via Vose<Family>FitObject on a
  scratch sheet, report tail-dependence (lower/upper/both/none). Dependence
  fitted FROM data. New bridge method fit_and_rank_copulas mirrors
  fit_and_rank (adds the copula FitObject's Data_In_Rows arg).
- reverse_stress_test (analysis): partition iterations breach/no-breach and
  profile each input's shift inside the breach set + extract a named stress
  scenario. Pure Python over .vmrs samples (reverse_stress_profile is
  factored out and unit-tested exactly).
- fit_all_data_and_wire (workflows): fit marginals + copula and wire a
  correlated model (Vose<Family>Fit(range,unc,U) linked to the copula U
  block), atomic with rollback, dry_run preview.
- build_model_from_brief (workflows): deterministic workbook -> wrapped
  outputs + VoseInput distributions -> validating sim -> headline
  percentiles, in one atomic reversible pass.

Adds a _ChangeSet staged-write/rollback wrapper over safe_write_cell (repo
had only per-cell restore before). New schemas in schemas/analysis.py.
14 new unit tests (pure logic + mocked-bridge + rollback); real-Excel wiring
via gated integration tests. 620 unit tests green; ruff + mypy clean.
Version 0.3.7 -> 0.3.8; tool count 56.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: vosesoft

CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to ModelRisk MCP. Follows [Keep a Changelog](https://keepach
 
 ## [Unreleased]
 
+## [0.3.8] — 2026-07-05
+
+### Four functional tools that widen the "does the work" gap vs. advisory agents
+
+Capabilities that structurally require *running the engine* and *holding the per-iteration joint sample matrix* — things an advisory copilot cannot do:
+
+- **`fit_copula_to_data`** — fit parametric copulas (Normal / T / Clayton / Frank / Gumbel) to a multi-column data range, rank by AIC/SIC/HQIC (`Vose<Family>FitObject` scored via `VoseAIC/SIC/HQIC` on a transient scratch sheet), and report the winner's **tail-dependence** character (lower = crash-together, upper = boom-together, both = T). Dependence fitted *from data*, capturing joint-tail risk a single correlation coefficient discards.
+- **`reverse_stress_test`** — from a bad output outcome back to the joint input state that causes it: partitions iterations into breach / no-breach (threshold or percentile, above/below), reports each input's mean shift (in its own SDs) inside the breach set and its tail concentration (a breach-driver tornado), and extracts the mean input vector as a concrete named stress scenario. The Solvency II / PRA reverse-stress-test, pure Python over the recorded `.vmrs` sample matrix.
+- **`fit_all_data_and_wire`** — fit both the marginals *and* the copula from a data block and wire the whole **correlated** model into the workbook (each marginal `Vose<Family>Fit(range, unc, U)` linked to the fitted copula's correlated-U block). One atomic pass with full rollback; `dry_run=True` previews the exact formulas.
+- **`build_model_from_brief`** — turn a deterministic workbook into a simulation-ready model in one atomic, reversible pass: wrap outputs with `VoseOutput`, replace input cells with `VoseInput`-wrapped distributions you choose, optionally run a validating simulation, and return the headline percentiles. Every write goes through the audit-logged safe-write path inside a **change-set** — any mid-build failure rolls back the entire build so the workbook is never left half-converted.
+
+Both orchestrators add a staged change-set/rollback wrapper over `safe_write_cell` (the repo previously had only per-cell restore). 14 new unit tests (pure breach-partition logic + mocked-bridge wrapper/rollback tests); real-Excel wiring is covered by the gated integration suite. 620 unit tests green; ruff + mypy clean. Tool count 56.
+
 ## [0.3.7] — 2026-06-18
 
 ### Distribution charts: `create_histogram_chart` + `create_cdf_chart`

README.md

@@ -234,7 +234,7 @@ The server can both read *and* modify your workbook — that's the central diffe
 
 ## What's inside
 
-- **52 tools** — 12 reading, 14 building (incl. `create_aggregate` for FFT / Panjer / MC frequency-severity methods), 5 simulation (incl. `run_simulation`, `run_scenarios`, `get_samples`, `restore_cell`, `restore_deterministic_state`), 8 analysis (`compute_distribution`, `fit_and_rank_distributions`, `get_tail_risk`, `fit_tail`, `compute_correlation_matrix`, `compare_distributions`, `backtest_output`, `decompose_uncertainty`), 10 workflow / reporting (incl. `plan_risk_model`, `audit_model`, `diagnose_workbook`, `create_tornado_chart`, `create_histogram_chart`, `create_cdf_chart`, `build_drivers_report`, `build_executive_report`, `generate_executive_summary`, `save_workbook_as`), 3 VMRS (`read_vmrs`, `set_active_vmrs`, `list_vmrs_variables`)
+- **56 tools** — 12 reading, 14 building (incl. `create_aggregate` for FFT / Panjer / MC frequency-severity methods), 5 simulation (incl. `run_simulation`, `run_scenarios`, `get_samples`, `restore_cell`, `restore_deterministic_state`), 10 analysis (`compute_distribution`, `fit_and_rank_distributions`, `fit_copula_to_data`, `reverse_stress_test`, `get_tail_risk`, `fit_tail`, `compute_correlation_matrix`, `compare_distributions`, `backtest_output`, `decompose_uncertainty`), 12 workflow / reporting (incl. `plan_risk_model`, `build_model_from_brief`, `fit_all_data_and_wire`, `audit_model`, `diagnose_workbook`, `create_tornado_chart`, `create_histogram_chart`, `create_cdf_chart`, `build_drivers_report`, `build_executive_report`, `generate_executive_summary`, `save_workbook_as`), 3 VMRS (`read_vmrs`, `set_active_vmrs`, `list_vmrs_variables`)
 - **5 resources** — `modelrisk://functions`, `modelrisk://distributions`, `modelrisk://methodology`, `modelrisk://workbook/current`, `modelrisk://audit-rules`
 - **5 slash-command prompts** — `/build-risk-model`, `/audit-model`, `/interpret-results`, `/add-uncertainty`, `/import-legacy-model`
 - **1417-entry function catalogue** extracted directly from the ModelRisk IDL + XLL header

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "modelrisk-mcp"
-version = "0.3.7"
+version = "0.3.8"
 description = "Open MCP server bridging Anthropic Claude (and any MCP-compatible client) with the ModelRisk Excel add-in."
 readme = "README.md"
 requires-python = ">=3.11"

server.json

@@ -3,12 +3,12 @@
   "name": "io.github.vosesoftware/modelrisk-mcp",
   "title": "ModelRisk",
   "description": "Read, build, fit, and run Monte Carlo risk models in Excel through Vose Software's ModelRisk.",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "modelrisk-mcp",
-      "version": "0.3.7",
+      "version": "0.3.8",
       "transport": {
         "type": "stdio"
       }

src/modelrisk_mcp/__init__.py

@@ -1 +1 @@
-__version__ = "0.3.7"
+__version__ = "0.3.8"

src/modelrisk_mcp/bridge/modelrisk.py

@@ -475,6 +475,88 @@ def fit_and_rank(
 
         return scored, skipped, sample_size
 
+    def fit_and_rank_copulas(
+        self,
+        data_range: str,
+        families: list[str],
+        *,
+        data_in_rows: bool = False,
+        workbook: str | None = None,
+        uncertainty: bool = False,
+    ) -> tuple[list[dict[str, Any]], list[dict[str, str]], int]:
+        """Fit each copula `family` to a multi-column `data_range` and
+        return its AIC/SIC/HQIC — the dependence structure fitted *from
+        data*, ranked like distributions.
+
+        Mirrors `fit_and_rank` exactly, but the copula fit-object
+        functions take a `Data_In_Rows` flag as well as the uncertainty
+        flag: `Vose<Family>FitObject(range, data_in_rows, uncertainty)`.
+        `family` names are catalogue stems like `CopulaMultiClayton`
+        (the tool passes the Multi* families, which handle any n>=2).
+
+        `data_range` must be sheet-qualified. Returns
+        `(scored, skipped, cell_count)` where `cell_count` is the total
+        numeric cell count (the caller divides by the variable count to
+        get the joint-observation row count)."""
+        self.ensure_modelrisk_functional()
+        unc = "TRUE" if uncertainty else "FALSE"
+        dir_flag = "TRUE" if data_in_rows else "FALSE"
+
+        valid: list[str] = []
+        skipped: list[dict[str, str]] = []
+        for fam in families:
+            if f"Vose{fam}FitObject" in self._catalogue:
+                valid.append(fam)
+            else:
+                skipped.append(
+                    {"family": fam, "reason": "no Vose<Family>FitObject in catalogue"}
+                )
+
+        scored: list[dict[str, Any]] = []
+        cell_count = 0
+        if valid:
+            with self._scratch_sheet(workbook) as (app, sht):
+                sht.range("F1").formula = f"=COUNT({data_range})"
+                for i, fam in enumerate(valid):
+                    r = i + 1
+                    sht.range((r, 1)).formula = (
+                        f"=Vose{fam}FitObject({data_range},{dir_flag},{unc})"
+                    )
+                    sht.range((r, 2)).formula = f"=VoseAIC(A{r})"
+                    sht.range((r, 3)).formula = f"=VoseSIC(A{r})"
+                    sht.range((r, 4)).formula = f"=VoseHQIC(A{r})"
+                app.api.CalculateFull()
+                try:
+                    cell_count = int(sht.range("F1").value or 0)
+                except (TypeError, ValueError):
+                    cell_count = 0
+                for i, fam in enumerate(valid):
+                    r = i + 1
+                    aic = sht.range((r, 2)).value
+                    sic = sht.range((r, 3)).value
+                    hqic = sht.range((r, 4)).value
+                    if all(
+                        isinstance(v, (int, float)) and not isinstance(v, bool)
+                        for v in (aic, sic, hqic)
+                    ):
+                        scored.append(
+                            {
+                                "family": fam,
+                                "aic": float(aic),
+                                "sic": float(sic),
+                                "hqic": float(hqic),
+                            }
+                        )
+                    else:
+                        reason = next(
+                            (str(v) for v in (aic, sic, hqic)
+                             if not isinstance(v, (int, float))),
+                            "fit failed",
+                        )
+                        skipped.append({"family": fam, "reason": reason})
+
+        return scored, skipped, cell_count
+
     # ------------------------------------------------------------------
     # Run sim — wraps SimulationController + auto-pins the resulting
     # .vmrs as the active source so subsequent get_simulation_results

src/modelrisk_mcp/schemas/analysis.py

@@ -252,3 +252,161 @@ class UncertaintyDecomposition(BaseModel):
     interpretation: str = Field(
         description="Which uncertainty dominates and what reduces it."
     )
+
+
+class CopulaFitCandidate(BaseModel):
+    """Goodness-of-fit scores for one fitted copula family. Lower
+    information criteria are better fits."""
+
+    family: str = Field(description="Copula family, e.g. 'CopulaMultiClayton'.")
+    aic: float = Field(description="Akaike information criterion (lower = better).")
+    sic: float = Field(description="Schwarz/Bayesian information criterion (lower = better).")
+    hqic: float = Field(description="Hannan-Quinn information criterion (lower = better).")
+    rank: int = Field(description="1 = best fit by the chosen criterion.")
+    tail_dependence: str = Field(
+        description=(
+            "Asymmetric tail-dependence character of the family: 'none' "
+            "(Normal/Frank), 'lower' (Clayton — joint crashes), 'upper' "
+            "(Gumbel — joint booms), or 'both' (T). This is what a single "
+            "correlation coefficient throws away."
+        )
+    )
+
+
+class CopulaFitRanking(BaseModel):
+    """Result of fitting and ranking parametric copula families to a
+    multi-column data range — the dependence structure *fitted from
+    data*, not merely constructed."""
+
+    data_range: str
+    n_variables: int = Field(description="Number of variables (columns) the copula spans.")
+    criterion: str = Field(description="Criterion the ranking is sorted by (AIC / SIC / HQIC).")
+    sample_size: int = Field(description="Number of joint observations (rows).")
+    best_family: str | None = Field(
+        default=None, description="Top-ranked copula family, or null if every fit failed."
+    )
+    candidates: list[CopulaFitCandidate] = Field(
+        description="Successfully-fitted copula families, best first."
+    )
+    skipped: list[dict[str, str]] = Field(
+        default_factory=list,
+        description="Families that could not be fitted, with a reason each.",
+    )
+    note: str = Field(description="Interpretation of the winning family's tail behaviour.")
+
+
+class BreachDriver(BaseModel):
+    """One input's behaviour conditional on the output breaching the
+    stress threshold — the inverse of a forward tornado."""
+
+    input_name: str
+    marginal_mean: float = Field(description="The input's mean across all iterations.")
+    breach_mean: float = Field(description="The input's mean across only the breach iterations.")
+    mean_shift_sd: float = Field(
+        description=(
+            "Standardised departure = (breach_mean - marginal_mean) / marginal_stdev. "
+            "Large magnitude ⇒ this input is systematically different when things go wrong."
+        )
+    )
+    breach_share_of_own_tail: float = Field(
+        description=(
+            "Fraction of this input's own worst-decile iterations that fall in the "
+            "breach set — how concentrated breaches are in this input's tail."
+        )
+    )
+    rank: int = Field(description="1 = strongest breach driver by |mean_shift_sd|.")
+
+
+class StressScenario(BaseModel):
+    """A concrete named input state extracted from the breach iterations."""
+
+    label: str
+    input_values: dict[str, float] = Field(
+        description="Per-input value (the mean input vector over the breach set)."
+    )
+
+
+class ReverseStressResult(BaseModel):
+    """Reverse stress test: from a bad output outcome back to the joint
+    input state that produced it (Solvency II / PRA style). Pure analysis
+    over the recorded per-iteration sample matrix — impossible without
+    the engine's joint samples."""
+
+    output_name: str
+    threshold: float
+    direction: str = Field(description="'above' or 'below' — the breach side of the threshold.")
+    iterations: int
+    breach_count: int
+    breach_probability: float
+    drivers: list[BreachDriver] = Field(
+        description="Inputs ranked by how far they shift in the breach set."
+    )
+    scenario: StressScenario | None = Field(
+        default=None, description="The mean input vector over the breach iterations."
+    )
+    note: str
+
+
+class WiredColumnResult(BaseModel):
+    """Outcome of fitting + wiring one data column as a model input."""
+
+    input_name: str
+    target_cell: str
+    best_family: str | None
+    formula: str
+    written: bool
+    skipped_reason: str | None = None
+
+
+class FitAndWireResult(BaseModel):
+    """Outcome of fitting marginals + a copula from data and wiring them
+    into the workbook as a correlated, simulation-ready model."""
+
+    workbook: str
+    sheet: str
+    columns: list[WiredColumnResult]
+    copula_family: str | None = Field(
+        default=None, description="Best-fit copula family wired across the columns, if any."
+    )
+    copula_anchor: str | None = Field(
+        default=None, description="Range where the correlated-U block was written."
+    )
+    dry_run: bool
+    simulated: bool = Field(description="Whether a validating simulation was run.")
+    achieved_correlation: list[list[float]] | None = Field(
+        default=None, description="Rank correlation of the wired inputs from the validating run."
+    )
+    rolled_back: bool = Field(
+        default=False, description="True if a mid-build failure triggered a full rollback."
+    )
+    steps: list[str] = Field(description="Ordered log of what happened.")
+    note: str
+
+
+class BuiltInput(BaseModel):
+    """One input the brief-builder created."""
+
+    cell: str
+    input_name: str
+    formula: str
+    source: str = Field(description="'fitted-from-data', 'proposed', or 'existing'.")
+
+
+class ModelFromBriefResult(BaseModel):
+    """Outcome of turning a deterministic workbook into a simulation-ready
+    Monte Carlo model in one orchestrated, reversible pass."""
+
+    workbook: str
+    dry_run: bool
+    outputs_wrapped: list[str] = Field(default_factory=list)
+    inputs_built: list[BuiltInput] = Field(default_factory=list)
+    correlated: bool = Field(default=False)
+    simulated: bool = Field(default=False)
+    headline: dict[str, dict[str, float]] = Field(
+        default_factory=dict,
+        description="Per-output headline stats (mean/P10/P50/P90) from the validating run.",
+    )
+    rolled_back: bool = Field(default=False)
+    change_set_size: int = Field(description="Number of cells written (0 if dry_run).")
+    steps: list[str] = Field(description="Ordered, human-readable log of the build.")
+    note: str