voting-mcp 0.1.0__py3-none-any.whl

voting_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""voting-mcp: principled social-choice aggregation rules as MCP tools."""
+
+__version__ = "0.1.0"

voting_mcp/aggregate.py

@@ -0,0 +1,54 @@
+"""Dispatch: map a rule name to its implementation and apply it to a profile."""
+
+from collections.abc import Callable
+from enum import StrEnum
+
+from voting_mcp.rules import (
+    approval,
+    borda,
+    condorcet,
+    copeland,
+    majority,
+    opinion_pool,
+    plurality,
+    stv,
+)
+from voting_mcp.types import Profile, Result, TieBreak
+
+
+class RuleName(StrEnum):
+    """Canonical names of the aggregation rules (used as the tool enum)."""
+
+    BORDA = "borda"
+    COPELAND = "copeland"
+    CONDORCET = "condorcet"
+    APPROVAL = "approval"
+    STV = "stv"
+    OPINION_POOL = "opinion_pool"
+    PLURALITY = "plurality"
+    MAJORITY = "majority"
+
+
+_RuleFn = Callable[..., Result]
+
+_DISPATCH: dict[RuleName, _RuleFn] = {
+    RuleName.BORDA: borda.borda,
+    RuleName.COPELAND: copeland.copeland,
+    RuleName.CONDORCET: condorcet.condorcet,
+    RuleName.APPROVAL: approval.approval,
+    RuleName.STV: stv.stv,
+    RuleName.OPINION_POOL: opinion_pool.opinion_pool,
+    RuleName.PLURALITY: plurality.plurality,
+    RuleName.MAJORITY: majority.majority,
+}
+
+
+def aggregate(
+    profile: Profile,
+    rule: RuleName,
+    *,
+    tie_break: TieBreak = TieBreak.LEXICOGRAPHIC,
+    seed: int = 0,
+) -> Result:
+    """Apply ``rule`` to ``profile``. Raises ``ValueError`` on a ballot-kind mismatch."""
+    return _DISPATCH[rule](profile, tie_break=tie_break, seed=seed)

voting_mcp/rules/__init__.py

@@ -0,0 +1,23 @@
+"""Social-choice rules. Each module exposes one pure ``(Profile) -> Result``."""
+
+from voting_mcp.rules import (
+    approval,
+    borda,
+    condorcet,
+    copeland,
+    majority,
+    opinion_pool,
+    plurality,
+    stv,
+)
+
+__all__ = [
+    "approval",
+    "borda",
+    "condorcet",
+    "copeland",
+    "majority",
+    "opinion_pool",
+    "plurality",
+    "stv",
+]

voting_mcp/rules/_common.py

@@ -0,0 +1,69 @@
+"""Shared ballot-extraction and pairwise helpers for the rules.
+
+Each extractor enforces that the profile carries the ballot kind a rule needs,
+raising a clear ``ValueError`` rather than silently coercing a mismatched kind.
+"""
+
+from voting_mcp.types import (
+    ApprovalBallot,
+    DistributionBallot,
+    Profile,
+    RankingBallot,
+)
+
+
+def rankings(profile: Profile, rule: str) -> list[tuple[list[str], float]]:
+    """Return ``(ranking, weight)`` pairs; raise if any ballot is not a ranking."""
+    out: list[tuple[list[str], float]] = []
+    for ballot in profile.ballots:
+        if not isinstance(ballot, RankingBallot):
+            raise ValueError(f"{rule} requires ranking ballots; got a {ballot.kind} ballot")
+        out.append((ballot.ranking, ballot.weight))
+    return out
+
+
+def approvals(profile: Profile, rule: str) -> list[tuple[list[str], float]]:
+    """Return ``(approved, weight)`` pairs; raise if any ballot is not approval."""
+    out: list[tuple[list[str], float]] = []
+    for ballot in profile.ballots:
+        if not isinstance(ballot, ApprovalBallot):
+            raise ValueError(f"{rule} requires approval ballots; got a {ballot.kind} ballot")
+        out.append((ballot.approved, ballot.weight))
+    return out
+
+
+def distributions(profile: Profile, rule: str) -> list[tuple[dict[str, float], float]]:
+    """Return ``(distribution, weight)`` pairs; raise if any ballot is not a dist."""
+    out: list[tuple[dict[str, float], float]] = []
+    for ballot in profile.ballots:
+        if not isinstance(ballot, DistributionBallot):
+            raise ValueError(f"{rule} requires distribution ballots; got a {ballot.kind} ballot")
+        out.append((ballot.distribution, ballot.weight))
+    return out
+
+
+def pairwise_tallies(profile: Profile, rule: str) -> dict[tuple[str, str], float]:
+    """Weighted pairwise preference tallies.
+
+    ``tally[(x, y)]`` is the total ballot weight that ranks ``x`` above ``y``.
+    A candidate ranked on a (possibly truncated) ballot is considered preferred
+    to every candidate absent from that ballot; if both are absent the ballot
+    abstains on that pair.
+    """
+    cands = profile.candidates
+    tally: dict[tuple[str, str], float] = {
+        (x, y): 0.0 for x in cands for y in cands if x != y
+    }
+    for ranking, weight in rankings(profile, rule):
+        pos = {c: i for i, c in enumerate(ranking)}
+        for x in cands:
+            for y in cands:
+                if x == y:
+                    continue
+                x_in, y_in = x in pos, y in pos
+                if x_in and y_in:
+                    if pos[x] < pos[y]:
+                        tally[(x, y)] += weight
+                elif x_in and not y_in:
+                    tally[(x, y)] += weight
+    return tally

voting_mcp/rules/approval.py

@@ -0,0 +1,19 @@
+"""Approval: each candidate scores the total weight of ballots approving it."""
+
+from voting_mcp.rules._common import approvals
+from voting_mcp.scoring import result_from_scores
+from voting_mcp.types import Profile, Result, TieBreak
+
+
+def approval(
+    profile: Profile,
+    *,
+    tie_break: TieBreak = TieBreak.LEXICOGRAPHIC,
+    seed: int = 0,
+) -> Result:
+    """Most-approved candidate wins. An empty approval set simply adds nothing."""
+    scores = dict.fromkeys(profile.candidates, 0.0)
+    for approved, weight in approvals(profile, "approval"):
+        for cand in approved:
+            scores[cand] += weight
+    return result_from_scores("approval", scores, tie_break=tie_break, seed=seed)

voting_mcp/rules/borda.py

@@ -0,0 +1,35 @@
+"""Borda count: positional scoring. Condorcet-inconsistent and clone-sensitive.
+
+With ``m`` candidates a ranked candidate at position ``i`` (0 = top) earns
+``m - 1 - i`` points. A truncated ballot ranks only ``k`` candidates: the
+unranked ones split the remaining low positions equally, each receiving the
+average ``(m - k - 1) / 2`` points rather than being coerced to zero.
+"""
+
+from voting_mcp.rules._common import rankings
+from voting_mcp.scoring import result_from_scores
+from voting_mcp.types import Profile, Result, TieBreak
+
+
+def borda(
+    profile: Profile,
+    *,
+    tie_break: TieBreak = TieBreak.LEXICOGRAPHIC,
+    seed: int = 0,
+) -> Result:
+    """Sum positional Borda points per candidate; highest total wins."""
+    m = len(profile.candidates)
+    scores = dict.fromkeys(profile.candidates, 0.0)
+
+    for ranking, weight in rankings(profile, "borda"):
+        k = len(ranking)
+        for i, cand in enumerate(ranking):
+            scores[cand] += weight * (m - 1 - i)
+        if k < m:
+            # Unranked candidates share the remaining points {0 .. m-k-1} equally.
+            avg_remaining = (m - k - 1) / 2 if m > k else 0.0
+            for cand in profile.candidates:
+                if cand not in ranking:
+                    scores[cand] += weight * avg_remaining
+
+    return result_from_scores("borda", scores, tie_break=tie_break, seed=seed)

voting_mcp/rules/condorcet.py

@@ -0,0 +1,48 @@
+"""Condorcet: the candidate that beats every other pairwise, or NO winner.
+
+When the majority relation has a cycle (e.g. a > b > c > a) no Condorcet winner
+exists; this returns empty ``winners`` and an explicit ``note`` rather than
+inventing a winner.
+"""
+
+from voting_mcp.rules._common import pairwise_tallies
+from voting_mcp.types import Profile, Result, TieBreak
+
+
+def condorcet(
+    profile: Profile,
+    *,
+    tie_break: TieBreak = TieBreak.LEXICOGRAPHIC,
+    seed: int = 0,
+) -> Result:
+    """Return the Condorcet winner, or no winner with a cycle note."""
+    tally = pairwise_tallies(profile, "condorcet")
+    cands = profile.candidates
+
+    winner: str | None = None
+    for x in cands:
+        if all(tally[(x, y)] > tally[(y, x)] for y in cands if y != x):
+            winner = x
+            break
+
+    # A descending pairwise-win ranking, useful even when no Condorcet winner exists.
+    wins = {x: sum(1 for y in cands if y != x and tally[(x, y)] > tally[(y, x)]) for x in cands}
+    ranking = sorted(cands, key=lambda c: (-wins[c], c))
+
+    if winner is None:
+        return Result(
+            rule="condorcet",
+            winners=[],
+            winner=None,
+            ranking=ranking,
+            tie_break=tie_break,
+            note="no Condorcet winner exists (the majority relation has a cycle)",
+        )
+    return Result(
+        rule="condorcet",
+        winners=[winner],
+        winner=winner,
+        ranking=ranking,
+        tie_break=tie_break,
+        note=None,
+    )

voting_mcp/rules/copeland.py

@@ -0,0 +1,29 @@
+"""Copeland: Condorcet-consistent pairwise scoring.
+
+Each candidate scores +1 for every opponent it beats pairwise and +0.5 for
+every pairwise tie. A Condorcet winner beats everyone and so tops the table.
+"""
+
+from voting_mcp.rules._common import pairwise_tallies
+from voting_mcp.scoring import result_from_scores
+from voting_mcp.types import Profile, Result, TieBreak
+
+
+def copeland(
+    profile: Profile,
+    *,
+    tie_break: TieBreak = TieBreak.LEXICOGRAPHIC,
+    seed: int = 0,
+) -> Result:
+    """Copeland score = (#pairwise wins) + 0.5 * (#pairwise ties)."""
+    tally = pairwise_tallies(profile, "copeland")
+    scores = dict.fromkeys(profile.candidates, 0.0)
+    for x in profile.candidates:
+        for y in profile.candidates:
+            if x == y:
+                continue
+            if tally[(x, y)] > tally[(y, x)]:
+                scores[x] += 1.0
+            elif tally[(x, y)] == tally[(y, x)]:
+                scores[x] += 0.5
+    return result_from_scores("copeland", scores, tie_break=tie_break, seed=seed)

voting_mcp/rules/majority.py

@@ -0,0 +1,49 @@
+"""Majority: a candidate wins only with a strict majority of first choices.
+
+This is the principled majority criterion, distinct from plurality: if no
+candidate holds more than half the vote weight, there is NO winner and the
+``note`` says so. (The bench's naive baseline uses plurality/mode; this rule is
+the stricter social-choice notion.)
+"""
+
+from voting_mcp.rules._common import rankings
+from voting_mcp.scoring import break_tie
+from voting_mcp.types import Profile, Result, TieBreak
+
+
+def majority(
+    profile: Profile,
+    *,
+    tie_break: TieBreak = TieBreak.LEXICOGRAPHIC,
+    seed: int = 0,
+) -> Result:
+    """Winner iff some candidate has > 50% of first-choice weight, else no winner."""
+    scores = dict.fromkeys(profile.candidates, 0.0)
+    for ranking, weight in rankings(profile, "majority"):
+        if ranking:
+            scores[ranking[0]] += weight
+
+    total = sum(scores.values())
+    ranking_order = sorted(scores, key=lambda c: (-scores[c], c))
+
+    leaders = [c for c, s in scores.items() if s == max(scores.values())]
+    top_votes = scores[leaders[0]] if leaders else 0.0
+    if total > 0 and len(leaders) == 1 and top_votes > total / 2:
+        winners = leaders
+        note = None
+    else:
+        winners = []
+        note = (
+            f"no majority winner: top candidate(s) {sorted(leaders)} hold "
+            f"{top_votes} of {total} vote weight (need > {total / 2})"
+        )
+
+    return Result(
+        rule="majority",
+        winners=winners,
+        winner=break_tie(winners, tie_break, seed),
+        ranking=ranking_order,
+        scores=scores,
+        tie_break=tie_break,
+        note=note,
+    )

voting_mcp/rules/opinion_pool.py

@@ -0,0 +1,31 @@
+"""Linear opinion pool: a weight-averaged probability distribution.
+
+Unlike the other rules this is NOT an argmax vote — it preserves the ensemble's
+confidence by pooling the full distributions: ``pooled[c] = (sum_b w_b *
+p_b[c]) / sum_b w_b``. The pooled distribution is returned in ``scores``; the
+winner is its argmax (with the usual tie-break) purely for convenience.
+"""
+
+from voting_mcp.rules._common import distributions
+from voting_mcp.scoring import result_from_scores
+from voting_mcp.types import Profile, Result, TieBreak
+
+
+def opinion_pool(
+    profile: Profile,
+    *,
+    tie_break: TieBreak = TieBreak.LEXICOGRAPHIC,
+    seed: int = 0,
+) -> Result:
+    """Pool distribution ballots linearly; ``scores`` is the pooled distribution."""
+    pooled = dict.fromkeys(profile.candidates, 0.0)
+    total_weight = 0.0
+    for dist, weight in distributions(profile, "opinion_pool"):
+        total_weight += weight
+        for cand, p in dist.items():
+            pooled[cand] += weight * p
+
+    if total_weight > 0:
+        pooled = {c: v / total_weight for c, v in pooled.items()}
+
+    return result_from_scores("opinion_pool", pooled, tie_break=tie_break, seed=seed)

voting_mcp/rules/plurality.py

@@ -0,0 +1,23 @@
+"""Plurality: the candidate with the most first-choice votes wins (baseline)."""
+
+from voting_mcp.rules._common import rankings
+from voting_mcp.scoring import result_from_scores
+from voting_mcp.types import Profile, Result, TieBreak
+
+
+def plurality(
+    profile: Profile,
+    *,
+    tie_break: TieBreak = TieBreak.LEXICOGRAPHIC,
+    seed: int = 0,
+) -> Result:
+    """Most first-place votes wins. Consumes ranking ballots (uses the top entry).
+
+    Ties for the most votes are surfaced in ``winners``; ``winner`` applies the
+    tie-break. This is the naive mode-of-votes baseline.
+    """
+    scores = dict.fromkeys(profile.candidates, 0.0)
+    for ranking, weight in rankings(profile, "plurality"):
+        if ranking:
+            scores[ranking[0]] += weight
+    return result_from_scores("plurality", scores, tie_break=tie_break, seed=seed)

voting_mcp/rules/stv.py

@@ -0,0 +1,74 @@
+"""Single-winner STV (a.k.a. instant-runoff): rounds of elimination + transfer.
+
+Each round counts every ballot's top *still-active* preference. If a candidate
+holds a strict majority of the active weight, it wins. Otherwise the candidate
+with the fewest votes is eliminated and its ballots transfer to their next
+active preference; a ballot with no remaining preference is *exhausted* and
+drops out of the active total. Clone-resistant, unlike plurality.
+
+Tie-breaks (both documented, deterministic):
+* elimination tie  -> eliminate the lexicographically largest candidate;
+* final-winner tie -> reported as co-winners, resolved by ``tie_break``.
+"""
+
+from voting_mcp.rules._common import rankings
+from voting_mcp.scoring import break_tie
+from voting_mcp.types import Profile, Result, TieBreak
+
+
+def _round_tally(
+    ballots: list[tuple[list[str], float]], active: set[str]
+) -> dict[str, float]:
+    scores = dict.fromkeys(active, 0.0)
+    for ranking, weight in ballots:
+        for cand in ranking:
+            if cand in active:
+                scores[cand] += weight
+                break  # first active preference only; else the ballot is exhausted
+    return scores
+
+
+def stv(
+    profile: Profile,
+    *,
+    tie_break: TieBreak = TieBreak.LEXICOGRAPHIC,
+    seed: int = 0,
+) -> Result:
+    """Run single-winner STV and return the winner (or final co-winners)."""
+    ballots = rankings(profile, "stv")
+    active = set(profile.candidates)
+    rounds = 0
+
+    while True:
+        rounds += 1
+        scores = _round_tally(ballots, active)
+        total = sum(scores.values())
+
+        if total > 0:
+            top = max(scores.values())
+            leaders = [c for c in active if scores[c] == top]
+            if len(leaders) == 1 and top > total / 2:
+                return Result(
+                    rule="stv",
+                    winners=leaders,
+                    winner=leaders[0],
+                    scores=scores,
+                    tie_break=tie_break,
+                    note=f"majority reached in round {rounds}",
+                )
+
+        if len(active) <= 2:
+            top = max(scores.values()) if scores else 0.0
+            winners = sorted(c for c in active if scores.get(c, 0.0) == top)
+            return Result(
+                rule="stv",
+                winners=winners,
+                winner=break_tie(winners, tie_break, seed),
+                scores=scores,
+                tie_break=tie_break,
+                note=f"resolved among final {len(active)} candidates in round {rounds}",
+            )
+
+        low = min(scores.values())
+        eliminate = max(c for c in active if scores[c] == low)
+        active.discard(eliminate)

voting_mcp/scoring.py

@@ -0,0 +1,64 @@
+"""Shared helpers for score-based rules: tie-breaking and Result assembly.
+
+Pure functions, deterministic. The tie-break policy only affects the single
+``Result.winner`` selection — ``Result.winners`` always reports the full set of
+candidates tied for the top, so a tie is never silently hidden.
+"""
+
+import math
+import random
+
+from voting_mcp.types import Result, TieBreak
+
+# Two scores within this absolute tolerance count as tied (guards float noise
+# in e.g. the linear opinion pool; exact for integer Borda/Copeland tallies).
+_SCORE_TOL = 1e-9
+
+
+def break_tie(tied: list[str], tie_break: TieBreak, seed: int = 0) -> str | None:
+    """Resolve a set of tied candidates to a single winner, or ``None``.
+
+    A lone candidate always resolves to itself. With more than one tied:
+    ``LEXICOGRAPHIC`` -> smallest id, ``RANDOM`` -> seeded order-independent
+    choice, ``NONE`` -> ``None`` (deliberately unresolved).
+    """
+    if not tied:
+        return None
+    if len(tied) == 1:
+        return tied[0]
+    if tie_break is TieBreak.LEXICOGRAPHIC:
+        return min(tied)
+    if tie_break is TieBreak.RANDOM:
+        return random.Random(seed).choice(sorted(tied))
+    return None  # TieBreak.NONE
+
+
+def result_from_scores(
+    rule: str,
+    scores: dict[str, float],
+    *,
+    tie_break: TieBreak = TieBreak.LEXICOGRAPHIC,
+    seed: int = 0,
+    note: str | None = None,
+) -> Result:
+    """Build a Result from a per-candidate score map (higher is better).
+
+    ``scores`` must cover every candidate. Winners are all candidates within
+    ``_SCORE_TOL`` of the maximum; the ranking sorts by descending score with
+    ties broken lexicographically so it is fully deterministic.
+    """
+    if not scores:
+        return Result(rule=rule, winners=[], winner=None, tie_break=tie_break, note=note)
+
+    top = max(scores.values())
+    winners = sorted(c for c, s in scores.items() if math.isclose(s, top, abs_tol=_SCORE_TOL))
+    ranking = sorted(scores, key=lambda c: (-scores[c], c))
+    return Result(
+        rule=rule,
+        winners=winners,
+        winner=break_tie(winners, tie_break, seed),
+        ranking=ranking,
+        scores=scores,
+        tie_break=tie_break,
+        note=note,
+    )

voting_mcp/server.py

@@ -0,0 +1,164 @@
+"""FastMCP server exposing the social-choice rules as tools.
+
+Transport is stdio only. The server is pure compute: no network, no file
+writes, no secrets — which keeps it clean against the OWASP MCP Top 10 by
+construction. Each tool's docstring is the model-facing spec; inputs and
+outputs are strict pydantic schemas (``additionalProperties: false``).
+
+Input (all tools): a ``profile`` = ``{candidates: [...], ballots: [...]}`` where
+each ballot has a ``kind`` ("ranking" | "approval" | "score" | "distribution")
+and an optional ``weight`` (default 1). ``tie_break`` is "lexicographic"
+(default), "none", or "random"; ``seed`` seeds the random tie-break.
+
+Output (all tools): a ``Result`` = ``{rule, winners, winner, ranking, scores,
+tie_break, note}``. ``winners`` is ALWAYS the full co-winner set (so ties are
+never hidden); ``winner`` is the single tie-broken pick, or ``null`` when no
+winner exists (e.g. a Condorcet cycle) or a tie is left unresolved.
+"""
+
+from mcp.server.fastmcp import FastMCP
+
+from voting_mcp.aggregate import RuleName, aggregate
+from voting_mcp.rules.approval import approval as _approval
+from voting_mcp.rules.borda import borda as _borda
+from voting_mcp.rules.condorcet import condorcet as _condorcet
+from voting_mcp.rules.copeland import copeland as _copeland
+from voting_mcp.rules.majority import majority as _majority
+from voting_mcp.rules.opinion_pool import opinion_pool as _opinion_pool
+from voting_mcp.rules.plurality import plurality as _plurality
+from voting_mcp.rules.stv import stv as _stv
+from voting_mcp.types import Profile, Result, TieBreak
+
+mcp = FastMCP("voting-mcp")
+
+
+@mcp.tool()
+def borda(profile: Profile, tie_break: TieBreak = TieBreak.LEXICOGRAPHIC, seed: int = 0) -> Result:
+    """Borda count over ranking ballots: positional scoring (top of m gets m-1).
+
+    Condorcet-inconsistent and clone-sensitive — useful as a contrast rule.
+    Truncated ballots give unranked candidates the average of the remaining
+    points (never a silent zero). Errors if any ballot is not a ranking.
+    """
+    return _borda(profile, tie_break=tie_break, seed=seed)
+
+
+@mcp.tool()
+def copeland(
+    profile: Profile, tie_break: TieBreak = TieBreak.LEXICOGRAPHIC, seed: int = 0
+) -> Result:
+    """Copeland over ranking ballots: +1 per pairwise win, +0.5 per pairwise tie.
+
+    Condorcet-consistent: a candidate that beats all others pairwise wins.
+    Errors if any ballot is not a ranking.
+    """
+    return _copeland(profile, tie_break=tie_break, seed=seed)
+
+
+@mcp.tool()
+def condorcet(
+    profile: Profile, tie_break: TieBreak = TieBreak.LEXICOGRAPHIC, seed: int = 0
+) -> Result:
+    """Condorcet winner over ranking ballots: beats every other candidate pairwise.
+
+    If the majority relation cycles (e.g. a>b>c>a) there is NO Condorcet winner:
+    ``winners`` is empty, ``winner`` is null, and ``note`` says so. Errors if any
+    ballot is not a ranking.
+    """
+    return _condorcet(profile, tie_break=tie_break, seed=seed)
+
+
+@mcp.tool()
+def approval(
+    profile: Profile, tie_break: TieBreak = TieBreak.LEXICOGRAPHIC, seed: int = 0
+) -> Result:
+    """Approval voting: each candidate scores the total weight approving it.
+
+    Consumes approval ballots (``{kind: "approval", approved: [...]}``). An empty
+    approval set is valid and adds nothing. Errors if any ballot is not approval.
+    """
+    return _approval(profile, tie_break=tie_break, seed=seed)
+
+
+@mcp.tool()
+def stv(profile: Profile, tie_break: TieBreak = TieBreak.LEXICOGRAPHIC, seed: int = 0) -> Result:
+    """Single-winner STV / instant-runoff over ranking ballots.
+
+    Rounds: count top active preferences; a strict majority wins, else eliminate
+    the fewest-voted (ties broken by eliminating the lexicographically largest)
+    and transfer. Ballots with no remaining preference are exhausted.
+    Clone-resistant. Errors if any ballot is not a ranking.
+    """
+    return _stv(profile, tie_break=tie_break, seed=seed)
+
+
+@mcp.tool()
+def opinion_pool(
+    profile: Profile, tie_break: TieBreak = TieBreak.LEXICOGRAPHIC, seed: int = 0
+) -> Result:
+    """Linear opinion pool over probability-distribution ballots.
+
+    Returns the weight-averaged distribution in ``scores`` (it PRESERVES
+    confidence rather than collapsing to an argmax vote); ``winner`` is the
+    argmax for convenience. Ballots are ``{kind: "distribution", distribution:
+    {cand: p, ...}}`` summing to 1. Errors if any ballot is not a distribution.
+    """
+    return _opinion_pool(profile, tie_break=tie_break, seed=seed)
+
+
+@mcp.tool()
+def plurality(
+    profile: Profile, tie_break: TieBreak = TieBreak.LEXICOGRAPHIC, seed: int = 0
+) -> Result:
+    """Plurality baseline over ranking ballots: most first-choice votes wins."""
+    return _plurality(profile, tie_break=tie_break, seed=seed)
+
+
+@mcp.tool()
+def majority(
+    profile: Profile, tie_break: TieBreak = TieBreak.LEXICOGRAPHIC, seed: int = 0
+) -> Result:
+    """Strict-majority rule over ranking ballots.
+
+    A candidate wins only with > 50% of first-choice weight; otherwise there is
+    NO winner (``winners`` empty, ``note`` explains). Distinct from plurality.
+    """
+    return _majority(profile, tie_break=tie_break, seed=seed)
+
+
+@mcp.tool()
+def aggregate_rule(
+    profile: Profile,
+    rule: RuleName,
+    tie_break: TieBreak = TieBreak.LEXICOGRAPHIC,
+    seed: int = 0,
+) -> Result:
+    """Apply any rule by name (enum ``rule``) — a single dispatch entrypoint.
+
+    Equivalent to the per-rule tools. ``rule`` is one of: borda, copeland,
+    condorcet, approval, stv, opinion_pool, plurality, majority.
+    """
+    return aggregate(profile, rule, tie_break=tie_break, seed=seed)
+
+
+def _enforce_strict_schemas() -> None:
+    """Set ``additionalProperties: false`` on every tool's top-level input.
+
+    FastMCP marks our nested pydantic models strict (via ``extra="forbid"``) but
+    leaves the outer argument object open; CLAUDE.md requires fully strict
+    schemas, so we close it here.
+    """
+    for tool in mcp._tool_manager.list_tools():
+        tool.parameters["additionalProperties"] = False
+
+
+_enforce_strict_schemas()
+
+
+def main() -> None:
+    """Console-script entrypoint: serve over stdio."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

voting_mcp/types.py

@@ -0,0 +1,145 @@
+"""Ballot / Profile / Result schemas.
+
+Design notes
+------------
+* Ballots are a discriminated union on ``kind``. ``extra="forbid"`` means an
+  unknown field is an error, not silently dropped.
+* A ``RankingBallot`` may be *strict* (lists every candidate) or *truncated*
+  (lists a subset) — both are valid; rules define how they treat the tail.
+* Cross-field validation (a ballot may only reference candidates in the
+  profile's candidate set) lives on ``Profile`` so it is enforced in one place.
+* ``Result.winners`` ALWAYS carries the full co-winner set, so a tie is never
+  hidden. ``Result.winner`` is the single tie-broken selection (``None`` when
+  there is no winner, e.g. a Condorcet cycle, or when ``tie_break=none`` leaves
+  a genuine tie unresolved).
+"""
+
+from enum import StrEnum
+from typing import Annotated, Literal, Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+# Tolerance for "a probability distribution sums to 1". Strict on purpose:
+# callers normalize before constructing — the type never silently coerces.
+_PROB_SUM_TOL = 1e-6
+
+
+class TieBreak(StrEnum):
+    """How a rule resolves a tie into the single ``Result.winner``.
+
+    The full tied set is always reported in ``Result.winners`` regardless.
+    """
+
+    LEXICOGRAPHIC = "lexicographic"  # smallest candidate id wins — deterministic default
+    NONE = "none"  # leave it unresolved: winner=None when >1 tied
+    RANDOM = "random"  # seeded choice — deterministic given the seed
+
+
+class _BallotBase(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+    weight: float = Field(default=1.0, gt=0.0)
+
+
+class RankingBallot(_BallotBase):
+    """An ordering of candidates, best first. May be truncated (a subset)."""
+
+    kind: Literal["ranking"] = "ranking"
+    ranking: list[str]
+
+    @model_validator(mode="after")
+    def _no_duplicates(self) -> Self:
+        if len(set(self.ranking)) != len(self.ranking):
+            raise ValueError("ranking contains duplicate candidates")
+        return self
+
+
+class ApprovalBallot(_BallotBase):
+    """A set of approved candidates."""
+
+    kind: Literal["approval"] = "approval"
+    approved: list[str]
+
+    @model_validator(mode="after")
+    def _no_duplicates(self) -> Self:
+        if len(set(self.approved)) != len(self.approved):
+            raise ValueError("approval set contains duplicate candidates")
+        return self
+
+
+class ScoreBallot(_BallotBase):
+    """A utility/score per candidate. No normalization constraint."""
+
+    kind: Literal["score"] = "score"
+    scores: dict[str, float]
+
+
+class DistributionBallot(_BallotBase):
+    """A probability distribution over candidates (sums to 1)."""
+
+    kind: Literal["distribution"] = "distribution"
+    distribution: dict[str, float]
+
+    @model_validator(mode="after")
+    def _valid_distribution(self) -> Self:
+        for cand, p in self.distribution.items():
+            if not 0.0 <= p <= 1.0:
+                raise ValueError(f"probability for {cand!r} out of [0, 1]: {p}")
+        total = sum(self.distribution.values())
+        if abs(total - 1.0) > _PROB_SUM_TOL:
+            raise ValueError(f"distribution must sum to 1, got {total}")
+        return self
+
+
+Ballot = Annotated[
+    RankingBallot | ApprovalBallot | ScoreBallot | DistributionBallot,
+    Field(discriminator="kind"),
+]
+
+
+def _referenced_candidates(ballot: Ballot) -> set[str]:
+    """Every candidate a ballot mentions — used for subset validation."""
+    if isinstance(ballot, RankingBallot):
+        return set(ballot.ranking)
+    if isinstance(ballot, ApprovalBallot):
+        return set(ballot.approved)
+    if isinstance(ballot, ScoreBallot):
+        return set(ballot.scores)
+    return set(ballot.distribution)
+
+
+class Profile(BaseModel):
+    """A candidate set plus ballots, all over that same candidate set."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    candidates: list[str]
+    ballots: list[Ballot]
+
+    @model_validator(mode="after")
+    def _validate(self) -> Self:
+        if not self.candidates:
+            raise ValueError("candidate set must be non-empty")
+        if len(set(self.candidates)) != len(self.candidates):
+            raise ValueError("candidate set contains duplicates")
+        known = set(self.candidates)
+        for i, ballot in enumerate(self.ballots):
+            unknown = _referenced_candidates(ballot) - known
+            if unknown:
+                raise ValueError(
+                    f"ballot {i} references candidates not in the set: {sorted(unknown)}"
+                )
+        return self
+
+
+class Result(BaseModel):
+    """The outcome of applying a rule to a profile."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    rule: str
+    winners: list[str]  # full co-winner set; len>1 => tie; [] => no winner exists
+    winner: str | None  # single tie-broken selection; None if no winner / unresolved tie
+    ranking: list[str] | None = None  # full social ranking where the rule defines one
+    scores: dict[str, float] | None = None  # per-candidate score the winner derives from
+    tie_break: TieBreak = TieBreak.LEXICOGRAPHIC
+    note: str | None = None  # e.g. "no Condorcet winner exists (cycle a > b > c > a)"

voting_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: voting-mcp
+Version: 0.1.0
+Summary: MCP server exposing principled social-choice aggregation rules (Borda, Copeland, Condorcet, approval, STV, opinion pool), with a reproducible benchmark measuring their accuracy vs majority vote over an LLM ensemble.
+Author-email: Hrishi Kabra <kabrahrishi@gmail.com>
+License: MIT
+Keywords: aggregation,ensemble,mcp,social-choice,voting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.12
+Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: pydantic>=2.6
+Provides-Extra: bench
+Requires-Dist: matplotlib>=3.8; extra == 'bench'
+Requires-Dist: numpy>=1.26; extra == 'bench'
+Requires-Dist: openai>=1.30; extra == 'bench'
+Requires-Dist: python-dotenv>=1.0; extra == 'bench'
+Requires-Dist: pyyaml>=6.0; extra == 'bench'
+Description-Content-Type: text/markdown
+
+# voting-mcp
+
+**Principled social-choice aggregation as MCP tools — with a benchmark that measures the
+accuracy lift over naive majority vote.**
+
+Almost every multi-agent system aggregates votes with `Counter(votes).most_common(1)`, throwing
+away preference order and confidence. `voting-mcp` ships the real rules (Borda, Copeland,
+Condorcet, approval, STV, linear opinion pool) as callable MCP tools — each with its known
+axiomatic behavior and explicit, documented tie-breaking — plus a reproducible benchmark that
+aggregates a diverse ensemble of LLMs on a reasoning set and reports accuracy with bootstrap
+confidence intervals.
+
+The server is **pure compute**: stdio transport, no network, no file writes, no secrets — clean
+against the OWASP MCP Top 10 by construction.
+
+## Install
+
+```sh
+# run the server directly (once published)
+uvx voting-mcp
+
+# or from source
+git clone <repo> && cd voting-mcp
+uv sync
+uv run python -m voting_mcp.server
+```
+
+Add it to an MCP client (e.g. Claude Desktop `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "voting": { "command": "uvx", "args": ["voting-mcp"] }
+  }
+}
+```
+
+## Tools
+
+Every tool takes a `profile` (`{candidates, ballots}`) and returns a `Result` with the full
+co-winner set (`winners`, so ties are never hidden), the single tie-broken `winner` (or `null`
+when none exists), a `ranking`, per-candidate `scores`, and a `note`.
+
+| Tool | Ballots | Notes |
+|------|---------|-------|
+| `borda` | rankings | positional; Condorcet-inconsistent, clone-sensitive |
+| `copeland` | rankings | Condorcet-consistent pairwise (+1 win, +0.5 tie) |
+| `condorcet` | rankings | returns the pairwise winner **or an explicit no-winner on a cycle** |
+| `approval` | approval sets | most-approved wins |
+| `stv` | rankings | single-winner instant-runoff; clone-resistant |
+| `opinion_pool` | distributions | linear pool — **preserves confidence, not an argmax vote** |
+| `plurality` | rankings | baseline (most first choices) |
+| `majority` | rankings | strict >50% or **no winner** |
+| `aggregate_rule` | any | dispatch by a `rule` enum |
+
+Tie-breaking is an explicit parameter (`lexicographic` default, `none`, or seeded `random`).
+
+## Benchmark
+
+Aggregate an ensemble of 5 models (one OpenAI-compatible client via OpenRouter) on
+ARC-Challenge and compare each rule to the naive majority vote:
+
+```sh
+uv sync --extra bench
+uv run python -m bench.fetch_arc --limit 200
+# prints a cost estimate and STOPS; add --yes to actually call the API, --mock for a free dry run
+uv run python -m bench.run_ensemble --dataset bench/datasets/arc_challenge.jsonl --limit 200 --yes
+uv run python -m bench.compare --dataset bench/datasets/arc_challenge.jsonl --limit 200
+```
+
+Every raw response is cached under `bench/results/raw/`; re-runs never re-call the API, so
+aggregation tweaks are free.
+
+### Results
+
+5-model ensemble (gpt-4o-mini · gemini-2.5-flash-lite · deepseek-v3 · claude-haiku-4.5 ·
+glm-4.7), n = 200, bootstrap 95% CI. Two datasets of different difficulty; full write-up and
+both plots in [`RESULTS.md`](RESULTS.md).
+
+**MMLU-Pro (hard, baseline 73.5%) — the informative case:**
+
+| Rule | Accuracy | 95% CI | Δ vs majority |
+|------|---------:|:------:|--------------:|
+| **opinion_pool** | **0.755** | [0.695, 0.815] | **+0.020** |
+| **majority_vote (baseline)** | 0.735 | [0.679, 0.788] | — |
+| approval | 0.701 | [0.640, 0.757] | −0.035 |
+| stv | 0.693 | [0.630, 0.750] | −0.043 |
+| copeland | 0.647 | [0.580, 0.710] | −0.088 |
+| condorcet | 0.620 | [0.550, 0.685] | −0.115 |
+| majority (strict) | 0.590 | [0.520, 0.655] | −0.145 |
+| borda | 0.472 | [0.405, 0.540] | −0.263 |
+
+![MMLU-Pro](docs/accuracy_mmlu_pro.png)
+
+**The finding (honest):** the value isn't "fancy voting beats majority." It's that **the
+confidence-preserving rule (`opinion_pool`) wins** when the crowd is uncertain (+2.0pp, the only
+rule above baseline — though its CI still overlaps, so *suggestive, not conclusive*), while
+**forcing the distributions into full rankings actively hurts** — `borda` collapses to 0.472,
+far below majority, because with 10 options the tail of the ranking is mostly noise. Aggregate
+the confidence; don't throw it away. On **ARC-Challenge** (baseline 96.8%, near-ceiling) nothing
+separates — every rule lands within overlapping CIs. See [`RESULTS.md`](RESULTS.md).
+
+## Develop
+
+```sh
+uv run pytest -q
+uv run ruff check .
+uv run mypy --strict src
+# exercise the tools in the MCP Inspector:
+npx @modelcontextprotocol/inspector uv run python -m voting_mcp.server
+```
+
+> Note: if you keep this repo under an iCloud-synced folder (e.g. `~/Desktop`), iCloud can spawn
+> duplicate `.pth` files that intermittently break the editable install. Tests use
+> `pythonpath=src`; run the server with `PYTHONPATH=src` if an import fails, or move the repo
+> off the synced folder.
+
+## License
+
+MIT

voting_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+voting_mcp/__init__.py,sha256=fRNoL8wCTCDt7zF3yCVcDeGX37bix0GhOBq5Wt1v8_Y,98
+voting_mcp/aggregate.py,sha256=YpQunLKnOST_RgGx5OEETcolr7Sprt-bnvww3-kVeKs,1363
+voting_mcp/scoring.py,sha256=cXJjxd_1BAA5dsB6XgEqHOwixmCDioNgPI80ctFYfB8,2208
+voting_mcp/server.py,sha256=AYCvbI8s3YXkJv45hsgLzRTLw05Yk9FMWYDf7ZvXZNU,6221
+voting_mcp/types.py,sha256=doJlNXpmp-zY46F5UtGAcGy53BNioEYzfJQFcqvbIW0,5171
+voting_mcp/rules/__init__.py,sha256=sK2-vMqEzKtuoRx6JJ1Kc309JS4M6ZMEHOf2W4LSEk0,366
+voting_mcp/rules/_common.py,sha256=VI7cqKaAbqov5J6cxPY91c1ZuulI7UWluFNvs9WrmGw,2758
+voting_mcp/rules/approval.py,sha256=WOlhK7XyAsJGZON0Sg1sDNVI7AgWzYSjn3NFTn7ONuo,702
+voting_mcp/rules/borda.py,sha256=HrXowd1IcUg9itIRe_C9Kj8rGV91pHiqQBwiTnGd_T8,1372
+voting_mcp/rules/condorcet.py,sha256=_ksI19aMHPS5m22g5OIsZmlpvYmgIUFqaabd1Zo0oH0,1506
+voting_mcp/rules/copeland.py,sha256=aG8NZ6dYg1tVEpbovdQmzpE90zvMlt7hvz8q2Kv5OzU,1029
+voting_mcp/rules/majority.py,sha256=As7pN4j_szuavWeb7CI5VVx5Y2vMf-icpbDet7pj6Ko,1650
+voting_mcp/rules/opinion_pool.py,sha256=2l7nLXbYwNeVUDRfcgeAebhnuzEhdmpPerZtP6OdV8Q,1176
+voting_mcp/rules/plurality.py,sha256=7ZOai4dP46KWTcqmdiIg95UCtbhQmWW_rAjQ_Ccb6tQ,845
+voting_mcp/rules/stv.py,sha256=TIxVYNZmD22Kh5_rHSulrjIwxmKoXZ1ZgBqdPBDSyaU,2679
+voting_mcp-0.1.0.dist-info/METADATA,sha256=SZzr602nEcRy2eCMyUYbMoAA30romUdw34C3hFBVlvA,5914
+voting_mcp-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+voting_mcp-0.1.0.dist-info/entry_points.txt,sha256=IBy0FYDQFJoihQIBi66Y9U4d38-2FSfQUUCk1LO9BPs,54
+voting_mcp-0.1.0.dist-info/RECORD,,

voting_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

voting_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+voting-mcp = voting_mcp.server:main