Add set_input_distribution (0.0.23) — gap #9b: assign uncertainties to tree inputs

Put a ModelRisk Vose* distribution on a tree input (branch cash flow or
probability), the way the ModelChoice UI lets you type a distribution into
a cell. This is the decision-tree half of a Monte Carlo: once inputs are
distributions, run the simulation with modelrisk-mcp (it samples these cells
and collects the tree's output distribution).

Implemented purely as an _MC_Store edit + re-render — the distribution is
stored as the input cell's UserFormula and applied by the existing
MC_RenderStoredTree, so no new add-in command is needed and it ships via
PyPI alone. Branch values (MC_BV_) and probabilities (MC_BP_) only.

- bridge.set_input_formula: edit UserFormulas in the stored model, write back,
  re-render so the Vose formula lands in the cell.
- tools.set_input_distribution: resolve node/branch -> named range, normalize
  the formula, drive the bridge; validates kind and chance-only probability.
- schemas.InputDistributionResult; 5 unit tests; CHANGELOG/README; 22 tools.

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

Author: vosesoft

CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to `modelchoice-mcp`. Versions are tag-driven; pushing a
 `vX.Y.Z` tag publishes to PyPI via the release workflow.
 
+## 0.0.23
+- **`set_input_distribution`** — assign an uncertainty (a ModelRisk `Vose*`
+  distribution) to a tree input (branch cash flow or probability), the way the
+  UI lets you type a distribution into a cell. Stored as the input's
+  user-formula and re-rendered, so it persists. This is the decision-tree half
+  of a Monte Carlo: once inputs are distributions, run the simulation with
+  **modelrisk-mcp** (it samples these cells and collects the tree's output
+  distribution). Pure `_MC_Store` edit + re-render — no new add-in command.
+
 ## 0.0.22
 - **`build_mcda`** — build a multi-criteria (MCDA) model: tree + criteria
   (ordinal options, weights, direction) + aggregation + per-terminal scores.

README.md

@@ -4,7 +4,7 @@
 
 A sibling to [`modelrisk-mcp`](https://github.com/vosesoftware/modelrisk-mcp): where that server brings Monte Carlo risk modelling into a conversation, this one brings **decision analysis** — building, reading, rolling back, and analysing decision trees in Excel.
 
-> **Status: `0.0.22` — Phase 3 (build + drive).** 21 tools: build_tree / build_mcda / edit_tree (incl. add/remove options & outcomes) / build_control_panel / export_tree_json / import_tree_json / import_precisiontree, read + roll + verify, run_scenarios (what-if comparison), plus run_evpi / run_evii / run_risk_profile / run_robustness / run_sensitivity / run_decision_report (strategy/policy/brief/mcda/force-to-outcome/two-way) / run_analysis / read_sheet over ModelChoice's headless commands.
+> **Status: `0.0.23` — Phase 3 (build + drive).** 22 tools: build_tree / build_mcda / edit_tree (incl. add/remove options & outcomes) / set_input_distribution (put a Vose distribution on an input) / build_control_panel / export_tree_json / import_tree_json / import_precisiontree, read + roll + verify, run_scenarios (what-if comparison), plus run_evpi / run_evii / run_risk_profile / run_robustness / run_sensitivity / run_decision_report (strategy/policy/brief/mcda/force-to-outcome/two-way) / run_analysis / read_sheet over ModelChoice's headless commands.
 
 ## Tools
 
@@ -13,6 +13,7 @@ A sibling to [`modelrisk-mcp`](https://github.com/vosesoftware/modelrisk-mcp): w
 | `build_tree` | **Build a tree from a structured description** and write it into Excel (dry-run by default). Validates + rolls it back so you confirm the recommendation before writing. The build-from-a-prompt path. |
 | `build_mcda` | **Build a multi-criteria (MCDA) model** — for choices that aren't pure money. Give the tree + criteria (ordinal options, weights, direction), aggregation, and each terminal's option per criterion; the add-in computes the composite scores. Drives `MC_ApplyMcda_Auto`. |
 | `edit_tree` | **Tweak an existing tree** — change probabilities, payoffs, labels, or the objective, **add or remove whole options/outcomes** (`add_option` / `add_branch` / `remove_branch`), then re-roll it (dry-run by default). The "tweak it by talking" path. |
+| `set_input_distribution` | **Make a tree input uncertain** — put a ModelRisk `Vose*` distribution on a branch's cash flow or probability (like typing a distribution into the cell in the UI). The decision-tree half of a Monte Carlo: once inputs are distributions, run the simulation with **modelrisk-mcp** to get the tree's outcome distribution. Pure store-edit + re-render — no add-in command. |
 | `build_control_panel` | **Lift the tree's inputs into a control panel** at the top of the sheet — every probability and cash flow as a labelled cell, with the tree linked back to it, so you drive the whole model from one input block. Drives `MC_BuildControlPanel_Auto`. |
 | `export_tree_json` / `import_tree_json` | Round-trip a tree's raw ModelChoice JSON — export to save/share/version, import (validated) to write it back into a workbook. |
 | `import_precisiontree` | Import a PrecisionTree workbook (.xls/.xlsx) into ModelChoice — converts a copy (original untouched). Drives `MC_ImportPrecisionTree_Auto`. |

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "modelchoice-mcp"
-version = "0.0.22"
+version = "0.0.23"
 description = "An open Model Context Protocol server for Vose Software's ModelChoice decision-tree add-in for Excel."
 readme = "README.md"
 requires-python = ">=3.11"

src/modelchoice_mcp/__init__.py

@@ -1,4 +1,4 @@
 """ModelChoice MCP — an open Model Context Protocol server for Vose
 Software's ModelChoice decision-tree add-in for Excel."""
 
-__version__ = "0.0.22"
+__version__ = "0.0.23"

src/modelchoice_mcp/bridge.py

@@ -500,6 +500,42 @@ def render_tree(self, sheet_name: str, workbook: str | None = None) -> None:
                 "loaded? (The tree JSON was stored regardless.)"
             ) from exc
 
+    def set_input_formula(
+        self,
+        named_range: str,
+        formula: str,
+        sheet_name: str | None = None,
+        workbook: str | None = None,
+    ) -> str:
+        """Assign a cell formula (e.g. a ``=VoseNormal(...)`` distribution) to a
+        tree input named range, the way the UI lets you type a distribution into
+        a branch value/probability cell. Records it in the stored model's
+        ``UserFormulas`` (so it survives re-renders) and re-renders the tree so
+        the formula lands in the cell. Returns the tree sheet name.
+
+        Pure ``_MC_Store`` edit + render — no special add-in command beyond the
+        existing MC_RenderStoredTree. ModelRisk (via modelrisk-mcp) then samples
+        the formula during simulation."""
+        raw = self.read_store_raw(workbook)
+        if not raw:
+            raise ModelChoiceNotFoundError("Workbook has no ModelChoice tree store.")
+        trees = parse_store(raw)
+        if sheet_name is None:
+            sheet_name = next(iter(trees))
+        if sheet_name not in trees:
+            raise ModelChoiceNotFoundError(
+                f"Tree {sheet_name!r} not found. Available: {', '.join(trees)}."
+            )
+        model = json.loads(trees[sheet_name])
+        uf = model.get("UserFormulas")
+        if not isinstance(uf, dict):
+            uf = {}
+        uf[named_range] = formula
+        model["UserFormulas"] = uf
+        self.write_tree(json.dumps(model), sheet_name=sheet_name, workbook=workbook)
+        self.render_tree(sheet_name, workbook)
+        return sheet_name
+
     def read_sheet(
         self,
         sheet_name: str,

src/modelchoice_mcp/schemas.py

@@ -253,6 +253,24 @@ class McdaBuildResult(BaseModel):
     note: str
 
 
+class InputDistributionResult(BaseModel):
+    """Outcome of assigning an uncertainty (a Vose* distribution) to a tree
+    input — a branch value or probability — the way the ModelChoice UI lets
+    you type a distribution into a cell. The distribution is stored as the
+    cell's user-formula and re-rendered, ready for ModelRisk (via
+    modelrisk-mcp) to sample during a Monte Carlo simulation."""
+
+    tree: str = Field(description="Tree sheet the input belongs to.")
+    node_id: str = Field(description="Node whose branch/option the distribution was put on.")
+    outcome: str = Field(description="Branch/option label the distribution was assigned to.")
+    kind: str = Field(description="'value' (branch cash flow) or 'probability'.")
+    named_range: str = Field(
+        description="The MC_BV_/MC_BP_ named range now holding the distribution formula."
+    )
+    formula: str = Field(description="The cell formula assigned (e.g. '=VoseNormal(100,20)').")
+    note: str
+
+
 class TreeExport(BaseModel):
     """A tree's stored ModelChoice model JSON, for saving or sharing."""
 

src/modelchoice_mcp/tools.py

@@ -24,6 +24,7 @@
     EviiResult,
     EvpiResult,
     ImportResult,
+    InputDistributionResult,
     KeyValue,
     McdaBuildResult,
     McdaSpec,
@@ -1031,6 +1032,95 @@ def build_control_panel(
     )
 
 
+@mcp.tool(
+    description=(
+        "ModelChoice: Assign an UNCERTAINTY to a tree input — put a ModelRisk "
+        "`Vose*` distribution on a branch's cash flow or probability, the way the "
+        "ModelChoice UI lets you type a distribution into an input cell. Pass the "
+        "node id, the branch/option label, the distribution formula (e.g. "
+        "'VoseNormal(100,20)', 'VosePERT(80,100,150)'), and kind='value' (cash "
+        "flow) or 'probability'. The distribution is stored as the cell's "
+        "user-formula and re-rendered, so it survives edits. This is the "
+        "decision-tree half of a Monte Carlo: once inputs are distributions, run "
+        "the simulation with modelrisk-mcp (it samples these cells and collects "
+        "the tree's output distribution). Requires the add-in loaded with a tree "
+        "rendered. Branch values / probabilities only (not terminal payoffs)."
+    )
+)
+def set_input_distribution(
+    node_id: Annotated[str, Field(description="Node whose branch/option carries the input.")],
+    outcome: Annotated[
+        str, Field(description="The branch/option label to put the distribution on.")
+    ],
+    distribution: Annotated[
+        str,
+        Field(
+            description=(
+                "The ModelRisk distribution formula, e.g. 'VoseNormal(100,20)' or "
+                "'=VosePERT(80,100,150)'. A leading '=' is optional."
+            )
+        ),
+    ],
+    kind: Annotated[
+        str, Field(description="'value' (branch cash flow) or 'probability'.")
+    ] = "value",
+    tree_name: Annotated[
+        str | None, Field(description="Tree sheet name. Omit for the first tree.")
+    ] = None,
+    workbook_name: str | None = None,
+) -> InputDistributionResult:
+    k = kind.lower()
+    if k not in ("value", "probability"):
+        raise ValueError(f"kind must be 'value' or 'probability', got {kind!r}.")
+
+    bridge = get_bridge()
+    trees = bridge.list_trees(workbook_name)
+    if tree_name is None:
+        tree_name = next(iter(trees))
+    if tree_name not in trees:
+        raise TreeParseError(f"no tree {tree_name!r}; available: {', '.join(trees)}.")
+
+    tree = parse_model(trees[tree_name])
+    node = tree.nodes.get(node_id)
+    if node is None:
+        raise ValueError(f"node {node_id!r} not found in {tree_name!r}.")
+    branch = next((b for b in node.branches if b.name == outcome), None)
+    if branch is None:
+        names = ", ".join(b.name for b in node.branches) or "(none)"
+        raise ValueError(
+            f"node {node_id!r} ({node.name!r}) has no branch {outcome!r}. "
+            f"Branches: {names}."
+        )
+    if k == "probability" and node.kind != "chance":
+        raise ValueError(
+            f"kind='probability' is only valid on a chance node; {node_id!r} is a "
+            f"{node.kind} node. Use kind='value' for a decision option's cash flow."
+        )
+
+    prefix = "MC_BV_" if k == "value" else "MC_BP_"
+    named_range = f"{prefix}{node_id}_{branch.child_id}"
+    formula = distribution.strip()
+    if not formula.startswith("="):
+        formula = "=" + formula
+
+    sheet = bridge.set_input_formula(named_range, formula, tree_name, workbook_name)
+
+    return InputDistributionResult(
+        tree=sheet,
+        node_id=node_id,
+        outcome=outcome,
+        kind=k,
+        named_range=named_range,
+        formula=formula,
+        note=(
+            f"Put {formula} on {node.name!r} → {outcome!r} ({named_range}). It's now "
+            "an uncertain input. Run the Monte Carlo with modelrisk-mcp's "
+            "run_simulation (track the root EV cell as the output) to get the "
+            "tree's outcome distribution."
+        ),
+    )
+
+
 @mcp.tool(
     description=(
         "ModelChoice: Run a decision-analysis on the active tree and report the "
@@ -1429,5 +1519,6 @@ def read_sheet(
     "run_sensitivity",
     "run_utility",
     "set_bridge_for_testing",
+    "set_input_distribution",
     "verify_rollback",
 ]

tests/test_server.py

@@ -7,7 +7,7 @@
 
 
 def test_version_set() -> None:
-    assert __version__ == "0.0.22"
+    assert __version__ == "0.0.23"
 
 
 def test_server_name() -> None:

tests/test_tools.py

@@ -135,6 +135,12 @@ def build_control_panel(self, sheet_name: str | None = None,
         ]
         return {"sheet": sheet_name or "MC_Tree_1", "rows": rows}
 
+    def set_input_formula(self, named_range: str, formula: str,
+                          sheet_name: str | None = None,
+                          workbook: str | None = None) -> str:
+        self.input_formula = (named_range, formula)
+        return sheet_name or "MC_Tree_1"
+
     def write_tree(self, model_json: str, sheet_name: str | None = None,
                    workbook: str | None = None) -> str:
         self.written_json = model_json
@@ -276,6 +282,43 @@ def test_build_control_panel_parses_inputs(bridge: _FakeBridge) -> None:
     assert "persist across re-renders" in out.note
 
 
+def test_set_input_distribution_value(bridge: _FakeBridge) -> None:
+    from modelchoice_mcp.schemas import InputDistributionResult
+
+    out = tools.set_input_distribution("C", "Wet", "VoseNormal(50,10)", kind="value")
+    assert isinstance(out, InputDistributionResult)
+    # Wet -> child T2, value input => MC_BV_C_T2; leading '=' added.
+    assert out.named_range == "MC_BV_C_T2"
+    assert out.formula == "=VoseNormal(50,10)"
+    assert bridge.input_formula == ("MC_BV_C_T2", "=VoseNormal(50,10)")
+    assert out.tree == "MC_Tree_1"
+    assert "modelrisk-mcp" in out.note
+
+
+def test_set_input_distribution_probability(bridge: _FakeBridge) -> None:
+    out = tools.set_input_distribution(
+        "C", "Dry", "=VosePERT(0.3,0.5,0.7)", kind="probability"
+    )
+    # Dry -> child T1, probability input => MC_BP_C_T1; existing '=' kept.
+    assert out.named_range == "MC_BP_C_T1"
+    assert out.formula == "=VosePERT(0.3,0.5,0.7)"
+
+
+def test_set_input_distribution_rejects_probability_on_decision(bridge: _FakeBridge) -> None:
+    with pytest.raises(ValueError, match="chance node"):
+        tools.set_input_distribution("D", "Drill", "VoseUniform(0,1)", kind="probability")
+
+
+def test_set_input_distribution_unknown_branch(bridge: _FakeBridge) -> None:
+    with pytest.raises(ValueError, match="no branch"):
+        tools.set_input_distribution("C", "Nope", "VoseNormal(0,1)")
+
+
+def test_set_input_distribution_bad_kind(bridge: _FakeBridge) -> None:
+    with pytest.raises(ValueError, match=r"value.*probability"):
+        tools.set_input_distribution("C", "Wet", "VoseNormal(0,1)", kind="bogus")
+
+
 def test_run_utility(bridge: _FakeBridge) -> None:
     from modelchoice_mcp.schemas import UtilityResult