AB#2646 build_mcda: AHP pairwise weight elicitation (0.0.25)

Set weight_source="ahp" + an ahp_matrix (Saaty 1-9, (1+criteria) square,
ordered [financial, ...criteria]) to derive MCDA weights from pairwise
comparisons instead of entering them directly. The tool mirrors the add-in's
AhpCalculator (power-iteration eigenvector + Saaty consistency ratio) to show
the derived weights + CR in the preview, validates the matrix (square, sized,
positive), and forwards weightSource/ahpMatrix to MC_ApplyMcda_Auto, which
recomputes them authoritatively.

- schemas: McdaSpec.weight_source + ahp_matrix; McdaBuildResult.weight_source
  + weights + consistency_ratio (KeyValue moved above the MCDA models so the
  forward ref resolves).
- tools: _ahp_weights + _validate_ahp_matrix helpers; build_mcda branches on
  weight_source; 4 unit tests (consistent 3x3 -> [4/7,2/7,1/7], CR~0; commit
  forwards the matrix; missing/bad-size raise). README + CHANGELOG.

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.25
+- **`build_mcda` gains AHP weight elicitation (AB#2646)** — set
+  `weight_source="ahp"` and pass an `ahp_matrix` (Saaty 1-9 pairwise comparisons,
+  `(1 + criteria)` square, ordered `[financial, …criteria]`) instead of direct
+  weights. The tool computes the eigenvector weights + consistency ratio for the
+  preview and forwards `weightSource`/`ahpMatrix` to `MC_ApplyMcda_Auto`, which
+  recomputes them authoritatively (CR surfaced; CR > 0.10 flagged inconsistent).
+  `McdaBuildResult` now reports `weight_source`, `weights`, `consistency_ratio`.
+
 ## 0.0.24
 - **`/decision-tree-monte-carlo` prompt** — guides the cross-server Monte Carlo
   hand-off: assign `Vose*` distributions to a tree's uncertain inputs

README.md

@@ -4,14 +4,14 @@
 
 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.24` — 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.
+> **Status: `0.0.25` — 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
 
 | Tool | What it does |
 |---|---|
 | `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`. |
+| `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. Weights can be entered directly or derived from an **AHP pairwise-comparison matrix** (`weight_source="ahp"` → eigenvector weights + consistency ratio). 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`. |
@@ -58,7 +58,7 @@ The Python roller is validated against ModelChoice's own authoritative C# test (
 The original phased roadmap is delivered. Candidate next steps (not yet scheduled):
 
 - **Simulation hand-off (cross-server):** the `decision-tree-monte-carlo` prompt guides assigning distributions → wrapping the root EV as a ModelRisk output → running the simulation in `modelrisk-mcp` → reading the EV's output distribution back. A thin orchestration tool could automate the hand-off end-to-end.
-- **AHP weight elicitation for MCDA:** `build_mcda` v1 takes direct weights; the add-in's Core already ships an `AhpCalculator` (pairwise comparisons → eigenvector weights + consistency ratio). A future `build_mcda` could accept a pairwise matrix instead (tracked in ADO).
+- ~~**AHP weight elicitation for MCDA**~~ — *done (0.0.25, AB#2646):* `build_mcda` accepts a pairwise-comparison matrix (`weight_source="ahp"`) and derives the weights + consistency ratio via the add-in's `AhpCalculator`.
 
 ## Architecture
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "modelchoice-mcp"
-version = "0.0.24"
+version = "0.0.25"
 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.24"
+__version__ = "0.0.25"

src/modelchoice_mcp/schemas.py

@@ -211,6 +211,11 @@ class ScenarioComparison(BaseModel):
     note: str
 
 
+class KeyValue(BaseModel):
+    label: str
+    value: Any
+
+
 class CriterionSpec(BaseModel):
     """One non-financial MCDA criterion with discrete ordinal options."""
 
@@ -240,6 +245,22 @@ class McdaSpec(BaseModel):
         default_factory=dict,
         description="Per terminal: {terminal_id: {criterion_id: option_label}}.",
     )
+    weight_source: str = Field(
+        default="direct",
+        description=(
+            "'direct' uses the per-criterion `weight` + `financial_weight` fields; "
+            "'ahp' derives all weights from `ahp_matrix` (those fields are ignored)."
+        ),
+    )
+    ahp_matrix: list[list[float]] | None = Field(
+        default=None,
+        description=(
+            "AHP pairwise comparison matrix on Saaty's 1-9 scale — required when "
+            "weight_source='ahp'. Must be (1 + number_of_criteria) square, ordered "
+            "[financial, criterion0, criterion1, ...], positive, and reciprocal "
+            "across the diagonal (a[j][i] = 1/a[i][j], diagonal = 1)."
+        ),
+    )
 
 
 class McdaBuildResult(BaseModel):
@@ -250,6 +271,17 @@ class McdaBuildResult(BaseModel):
     node_count: int
     criteria: list[str] = Field(description="Criterion names defined.")
     terminals_scored: int
+    weight_source: str = Field(
+        default="direct", description="'direct' or 'ahp' — how the weights were set."
+    )
+    weights: list[KeyValue] = Field(
+        default_factory=list,
+        description="Effective weights (label -> weight): 'Financial' + each criterion.",
+    )
+    consistency_ratio: float | None = Field(
+        default=None,
+        description="AHP consistency ratio (CR < 0.10 acceptable); None for direct weights.",
+    )
     note: str
 
 
@@ -313,11 +345,6 @@ class SheetData(BaseModel):
     truncated: bool = Field(description="True if the sheet had more rows/cols than returned.")
 
 
-class KeyValue(BaseModel):
-    label: str
-    value: Any
-
-
 class RobustnessSummary(BaseModel):
     """Structured read of ModelChoice's robustness ('break the decision')
     analysis — how much inputs must change to flip the optimal choice."""

src/modelchoice_mcp/tools.py

@@ -166,6 +166,57 @@ def build_tree(
     )
 
 
+_AHP_RANDOM_INDEX = [
+    0.0, 0.0, 0.58, 0.90, 1.12, 1.24, 1.32, 1.41, 1.45, 1.49,
+    1.51, 1.48, 1.56, 1.57, 1.59,
+]
+
+
+def _ahp_weights(matrix: list[list[float]]) -> tuple[list[float], float]:
+    """AHP principal-eigenvector weights + consistency ratio, mirroring the
+    add-in's AhpCalculator (power iteration; Saaty's RI table). `matrix` is an
+    n-by-n positive reciprocal pairwise-comparison matrix; returns (weights, CR)."""
+    n = len(matrix)
+    w = [1.0 / n] * n
+    for _ in range(100):
+        t = [sum(matrix[i][j] * w[j] for j in range(n)) for i in range(n)]
+        s = sum(t)
+        if s < 1e-15:
+            raise ValueError("ahp_matrix is degenerate (zero column sum).")
+        t = [x / s for x in t]
+        converged = max(abs(t[i] - w[i]) for i in range(n)) < 1e-10
+        w = t
+        if converged:
+            break
+    if n <= 2:
+        return w, 0.0
+    lam = 0.0
+    for i in range(n):
+        aw = sum(matrix[i][j] * w[j] for j in range(n))
+        if w[i] > 1e-15:
+            lam += aw / w[i]
+    lam /= n
+    ci = (lam - n) / (n - 1)
+    ri = _AHP_RANDOM_INDEX[min(n, len(_AHP_RANDOM_INDEX)) - 1]
+    return w, (ci / ri if ri > 1e-15 else 0.0)
+
+
+def _validate_ahp_matrix(matrix: list[list[float]] | None, n: int) -> list[list[float]]:
+    """Validate an AHP matrix is present, n-by-n, and strictly positive."""
+    if not matrix:
+        raise ValueError("weight_source='ahp' requires ahp_matrix.")
+    if len(matrix) != n or any(len(row) != n for row in matrix):
+        raise ValueError(
+            f"ahp_matrix must be {n}x{n} (financial + {n - 1} criteria), "
+            "ordered [financial, then criteria in spec order]."
+        )
+    for i, row in enumerate(matrix):
+        for j, v in enumerate(row):
+            if isinstance(v, bool) or not isinstance(v, (int, float)) or v <= 0:
+                raise ValueError(f"ahp_matrix[{i}][{j}] must be a positive number.")
+    return matrix
+
+
 @mcp.tool(
     description=(
         "ModelChoice: Build a MULTI-CRITERIA (MCDA) decision model — when the "
@@ -175,9 +226,13 @@ def build_tree(
         "an aggregation method (weighted_sum / weighted_geometric / waspas), and "
         "each terminal's option per criterion (`terminal_scores`). The tool "
         "validates structure + weights + that every score references a real "
-        "criterion option. dry_run=True (default) previews; dry_run=False builds "
-        "the tree, sets MCDA mode, and renders — the add-in computes the "
-        "composite scores. Needs the add-in loaded (a build with the MCDA command)."
+        "criterion option. Weights are entered directly (weight_source='direct') "
+        "OR derived from an AHP pairwise-comparison matrix (weight_source='ahp' "
+        "with `ahp_matrix` — the tool computes the eigenvector weights + "
+        "consistency ratio and the add-in recomputes them authoritatively). "
+        "dry_run=True (default) previews; dry_run=False builds the tree, sets MCDA "
+        "mode, and renders — the add-in computes the composite scores. Needs the "
+        "add-in loaded (a build with the MCDA command)."
     )
 )
 def build_mcda(
@@ -197,8 +252,6 @@ def build_mcda(
         if len(c.options) < 2:
             raise ValueError(f"criterion {c.id!r} needs >=2 options.")
         crit_by_id[c.id] = c
-    weight_sum = mcda.financial_weight + sum(c.weight for c in mcda.criteria)
-
     term_ids = {n.id for n in tree.nodes if n.type.lower() == "terminal"}
     for tid, scores in mcda.terminal_scores.items():
         if tid not in term_ids:
@@ -214,9 +267,31 @@ def build_mcda(
 
     crit_names = [c.name for c in mcda.criteria]
     scored = len(mcda.terminal_scores)
-    weight_note = (
-        "" if abs(weight_sum - 1.0) < 1e-3 else f" (weights sum {weight_sum:.3f}, not 1.0)"
-    )
+    ws = mcda.weight_source.strip().lower()
+
+    # Resolve effective weights for preview/reporting. For AHP the matrix is
+    # authoritative (the add-in recomputes it on commit); we mirror the math
+    # here so the preview shows the derived weights + consistency ratio.
+    consistency_ratio: float | None = None
+    ahp_matrix: list[list[float]] | None = None
+    if ws == "ahp":
+        ahp_matrix = _validate_ahp_matrix(mcda.ahp_matrix, len(mcda.criteria) + 1)
+        derived, consistency_ratio = _ahp_weights(ahp_matrix)
+        financial_w, crit_w = derived[0], derived[1:]
+        weight_note = f" AHP weights (CR={consistency_ratio:.3f}" + (
+            "; INCONSISTENT, CR>0.10 — consider revising judgments)"
+            if consistency_ratio > 0.10
+            else ")"
+        )
+    else:
+        financial_w = mcda.financial_weight
+        crit_w = [c.weight for c in mcda.criteria]
+        total = financial_w + sum(crit_w)
+        weight_note = "" if abs(total - 1.0) < 1e-3 else f" (weights sum {total:.3f}, not 1.0)"
+
+    weights_kv = [KeyValue(label="Financial", value=round(financial_w, 4))] + [
+        KeyValue(label=c.name, value=round(crit_w[i], 4)) for i, c in enumerate(mcda.criteria)
+    ]
 
     if dry_run:
         return McdaBuildResult(
@@ -225,19 +300,23 @@ def build_mcda(
             node_count=len(t.nodes),
             criteria=crit_names,
             terminals_scored=scored,
+            weight_source=ws,
+            weights=weights_kv,
+            consistency_ratio=consistency_ratio,
             note=(
                 f"Validated MCDA preview: {len(crit_names)} criteria, {scored} terminals "
-                f"scored{weight_note}. Composite scores are computed by the add-in on commit."
+                f"scored;{weight_note}. Composite scores are computed by the add-in on commit."
             ),
         )
 
     bridge = get_bridge()
     sheet = bridge.write_tree(model_json, workbook=workbook_name)
     bridge.render_tree(sheet, workbook_name)
-    spec = {
+    spec: dict[str, Any] = {
         "financialWeight": mcda.financial_weight,
         "aggregation": mcda.aggregation,
         "waspasLambda": mcda.waspas_lambda,
+        "weightSource": ws,
         "criteria": [
             {
                 "id": c.id,
@@ -250,13 +329,18 @@ def build_mcda(
         ],
         "terminalScores": mcda.terminal_scores,
     }
+    if ahp_matrix is not None:
+        spec["ahpMatrix"] = ahp_matrix
     bridge.apply_mcda(json.dumps(spec), workbook_name)
     return McdaBuildResult(
         written=True,
         sheet=sheet,
         node_count=len(t.nodes),
         criteria=crit_names,
         terminals_scored=scored,
+        weight_source=ws,
+        weights=weights_kv,
+        consistency_ratio=consistency_ratio,
         note=(
             f"Built MCDA model on {sheet!r}: {len(crit_names)} criteria, {scored} "
             f"terminals scored, aggregation {mcda.aggregation}{weight_note}."

tests/test_server.py

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

tests/test_tools.py

@@ -596,6 +596,77 @@ def test_build_mcda_bad_option_raises(bridge: _FakeBridge) -> None:
         tools.build_mcda(tree, mcda)
 
 
+def _mcda_ahp_specs():
+    """Two non-financial criteria + a consistent 3x3 AHP matrix
+    [financial, cost, safety] proportional to weights [4, 2, 1]."""
+    from modelchoice_mcp.schemas import BranchSpec, CriterionSpec, McdaSpec, NodeSpec, TreeSpec
+
+    tree = TreeSpec(
+        root_id="D", model_name="Site", maximize=True,
+        nodes=[
+            NodeSpec(id="D", type="decision", name="Site", branches=[
+                BranchSpec(name="A", child_id="T1"),
+                BranchSpec(name="B", child_id="T2")]),
+            NodeSpec(id="T1", type="terminal", name="A", value=0),
+            NodeSpec(id="T2", type="terminal", name="B", value=0),
+        ],
+    )
+    mcda = McdaSpec(
+        criteria=[
+            CriterionSpec(id="cost", name="Cost", weight=0.0, maximize=False,
+                          options=["High", "Low"]),
+            CriterionSpec(id="safety", name="Safety", weight=0.0, maximize=True,
+                          options=["Low", "High"]),
+        ],
+        weight_source="ahp",
+        ahp_matrix=[[1.0, 2.0, 4.0], [0.5, 1.0, 2.0], [0.25, 0.5, 1.0]],
+        terminal_scores={"T1": {"cost": "Low", "safety": "Low"},
+                         "T2": {"cost": "High", "safety": "High"}},
+    )
+    return tree, mcda
+
+
+def test_build_mcda_ahp_dry_run(bridge: _FakeBridge) -> None:
+    tree, mcda = _mcda_ahp_specs()
+    out = tools.build_mcda(tree, mcda)
+    assert out.weight_source == "ahp"
+    # Perfectly consistent matrix -> CR ~ 0.
+    assert out.consistency_ratio is not None and out.consistency_ratio < 0.01
+    by_label = {kv.label: kv.value for kv in out.weights}
+    assert by_label["Financial"] == pytest.approx(4 / 7, abs=1e-3)
+    assert by_label["Cost"] == pytest.approx(2 / 7, abs=1e-3)
+    assert by_label["Safety"] == pytest.approx(1 / 7, abs=1e-3)
+
+
+def test_build_mcda_ahp_commit_sends_matrix() -> None:
+    fake = _FakeBridge({})
+    tools.set_bridge_for_testing(fake)  # type: ignore[arg-type]
+    try:
+        tree, mcda = _mcda_ahp_specs()
+        out = tools.build_mcda(tree, mcda, dry_run=False)
+        assert out.written is True and out.weight_source == "ahp"
+        import json as _json
+        spec = _json.loads(fake.mcda_spec)
+        assert spec["weightSource"] == "ahp"
+        assert spec["ahpMatrix"] == [[1.0, 2.0, 4.0], [0.5, 1.0, 2.0], [0.25, 0.5, 1.0]]
+    finally:
+        tools.set_bridge_for_testing(None)
+
+
+def test_build_mcda_ahp_missing_matrix_raises(bridge: _FakeBridge) -> None:
+    tree, mcda = _mcda_ahp_specs()
+    mcda.ahp_matrix = None
+    with pytest.raises(ValueError, match="requires ahp_matrix"):
+        tools.build_mcda(tree, mcda)
+
+
+def test_build_mcda_ahp_bad_size_raises(bridge: _FakeBridge) -> None:
+    tree, mcda = _mcda_ahp_specs()
+    mcda.ahp_matrix = [[1.0, 2.0], [0.5, 1.0]]  # 2x2, need 3x3 (financial + 2 criteria)
+    with pytest.raises(ValueError, match="3x3"):
+        tools.build_mcda(tree, mcda)
+
+
 def test_run_scenarios_compares(bridge: _FakeBridge) -> None:
     from modelchoice_mcp.schemas import ScenarioComparison, ScenarioSpec