hypermind 0.11.0__py3-none-any.whl

hypermind/simlab/modes/tournament.py

@@ -0,0 +1,448 @@
+"""Decision Tournament mode — pairwise bracket with Condorcet winner.
+
+The user submits 3–6 named *options* (acquire vs build vs partner;
+candidate A vs B vs C; vendor 1 vs 2 vs 3) plus a list of *criteria*
+(cost, time-to-value, risk, fit). The mode runs a round-robin
+tournament: every option faces every other option, evaluated against
+each criterion. Each match produces a signed receipt.
+
+The aggregate result includes:
+
+* a **Condorcet winner** (option that beats every other option in
+  pairwise comparisons), if one exists
+* a **Borda count** ranking (sum of wins)
+* a per-criterion sensitivity matrix — *"if you weighted criterion
+  X higher, would the winner change?"*
+* per-match dissents preserved as first-class records
+
+The headline UI visual is the bracket: a grid of pairwise matches,
+each a small card with criterion-by-criterion scores and a winner
+chip. Click a match to see the receipt and dissent.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from dataclasses import asdict, dataclass
+from itertools import combinations
+from pathlib import Path
+from typing import Any
+
+from . import ModeSpec, register
+
+# --- Result types ----------------------------------------------------------
+
+
+@dataclass
+class CriterionScore:
+    criterion: str
+    option_a_score: float  # 0..1
+    option_b_score: float  # 0..1
+    weight: float  # >= 0; user-provided; defaults to 1.0
+
+
+@dataclass
+class MatchDissent:
+    role: str
+    counter_winner: str
+    rationale: str
+
+
+@dataclass
+class Match:
+    match_id: str
+    option_a: str
+    option_b: str
+    scores: list[CriterionScore]
+    winner: str  # option_a | option_b | tie
+    margin: float  # weighted score difference, signed (+ favours a)
+    receipt_kid: str  # synthetic receipt identifier
+    dissents: list[MatchDissent]
+
+
+@dataclass
+class TournamentSummary:
+    winner_condorcet: str | None
+    winner_borda: str
+    borda_counts: dict[str, int]
+    pairwise_table: dict[str, dict[str, str]]  # row beats col?  "win"|"loss"|"tie"|"-"
+    sensitivity_pivots: list[dict[str, Any]]  # criterion → {weight_threshold, new_winner}
+    n_options: int
+    n_criteria: int
+
+
+# --- Input schema ----------------------------------------------------------
+
+INPUT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "title": "Decision Tournament",
+    "required": ["question", "options"],
+    "properties": {
+        "question": {
+            "type": "string",
+            "title": "Decision",
+            "format": "textarea",
+            "description": (
+                "What are you deciding? e.g. 'Acquire vs build vs partner "
+                "for the AI assistant initiative.'"
+            ),
+        },
+        "options": {
+            "type": "array",
+            "title": "Options (3–6, comma-separated)",
+            "description": "Named alternatives to compare.",
+            "examples": ["acquire-anthropic, build-in-house, partner-with-vendor"],
+            "default": [],
+        },
+        "criteria": {
+            "type": "array",
+            "title": "Criteria (each: 'name=weight', weight optional)",
+            "description": (
+                "e.g. 'cost=2,time=1,risk=2,fit=1'. Higher weight = "
+                "more decisive in the verdict. Default weight is 1."
+            ),
+            "examples": ["cost=2", "time-to-value=1", "regulatory-risk=3", "team-fit=1"],
+            "default": [],
+        },
+    },
+}
+
+
+RESULT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "mode": {"type": "string", "const": "decision-tournament"},
+        "question": {"type": "string"},
+        "options": {"type": "array"},
+        "matches": {"type": "array"},
+        "summary": {"type": "object"},
+    },
+}
+
+
+# --- Parsing ---------------------------------------------------------------
+
+
+def _parse_options(raw: list[str] | str) -> list[str]:
+    if isinstance(raw, str):
+        raw = [raw]
+    out: list[str] = []
+    for item in raw:
+        for piece in str(item).split(","):
+            piece = piece.strip()
+            if piece and piece not in out:
+                out.append(piece)
+    return out[:6]
+
+
+def _parse_criteria(raw: list[str] | str) -> list[tuple[str, float]]:
+    if isinstance(raw, str):
+        raw = [raw]
+    out: list[tuple[str, float]] = []
+    seen: set[str] = set()
+    for item in raw:
+        for piece in str(item).split(","):
+            piece = piece.strip()
+            if not piece:
+                continue
+            name, _, weight_str = piece.partition("=")
+            name = name.strip()
+            try:
+                weight = float(weight_str) if weight_str else 1.0
+            except ValueError:
+                weight = 1.0
+            if name and name not in seen:
+                out.append((name, weight))
+                seen.add(name)
+    return out
+
+
+def _seed_criteria_for_question(q: str) -> list[tuple[str, float]]:
+    """Default criteria when the user gives none."""
+    h = q.lower()
+    if "acquire" in h or "build" in h or "partner" in h or "vendor" in h:
+        return [("cost", 2.0), ("time-to-value", 1.0), ("strategic-fit", 2.0), ("risk", 1.5)]
+    if "candidate" in h or "hire" in h:
+        return [("technical-fit", 2.0), ("culture-fit", 2.0), ("ramp-time", 1.0), ("cost", 1.0)]
+    return [("value", 2.0), ("cost", 1.5), ("risk", 1.5), ("speed", 1.0)]
+
+
+# --- Synthetic scoring -----------------------------------------------------
+
+
+def _option_score(option: str, criterion: str) -> float:
+    """Map (option, criterion) → [0,1] deterministically. Includes a
+    structural lean (e.g. "build" tends to score high on strategic-fit
+    but low on time-to-value) plus a hash-based unique fingerprint."""
+    structural = 0.5
+    o = option.lower()
+    c = criterion.lower()
+    if "build" in o:
+        structural += {
+            "strategic-fit": +0.20,
+            "cost": -0.15,
+            "time-to-value": -0.20,
+            "risk": -0.10,
+            "value": +0.15,
+        }.get(c, 0.0)
+    if "acquire" in o:
+        structural += {
+            "time-to-value": +0.20,
+            "cost": -0.20,
+            "strategic-fit": +0.05,
+            "risk": -0.05,
+            "speed": +0.20,
+        }.get(c, 0.0)
+    if "partner" in o:
+        structural += {
+            "cost": +0.15,
+            "risk": +0.15,
+            "strategic-fit": -0.10,
+            "time-to-value": +0.10,
+        }.get(c, 0.0)
+    h = int(hashlib.sha256(f"{option}::{criterion}".encode()).hexdigest(), 16)
+    fingerprint = ((h % 41) - 20) / 100.0  # [-0.20, 0.20]
+    return max(0.0, min(1.0, structural + fingerprint))
+
+
+def _resolve_match(
+    option_a: str,
+    option_b: str,
+    criteria: list[tuple[str, float]],
+) -> tuple[list[CriterionScore], str, float]:
+    """Run a single pairwise match. Returns (scores, winner, margin)."""
+    scores: list[CriterionScore] = []
+    weighted_diff = 0.0
+    total_weight = 0.0
+    for name, weight in criteria:
+        a = _option_score(option_a, name)
+        b = _option_score(option_b, name)
+        scores.append(
+            CriterionScore(
+                criterion=name,
+                option_a_score=round(a, 3),
+                option_b_score=round(b, 3),
+                weight=weight,
+            )
+        )
+        weighted_diff += weight * (a - b)
+        total_weight += weight
+    normalised_margin = weighted_diff / max(total_weight, 0.001)
+    if abs(normalised_margin) < 0.02:
+        return scores, "tie", round(normalised_margin, 4)
+    winner = option_a if normalised_margin > 0 else option_b
+    return scores, winner, round(normalised_margin, 4)
+
+
+def _match_dissents(
+    scores: list[CriterionScore],
+    option_a: str,
+    option_b: str,
+    winner: str,
+) -> list[MatchDissent]:
+    """A criterion-as-dissenter: any criterion where the *loser* scored
+    materially higher (margin ≥ 0.15) becomes a dissent record."""
+    out: list[MatchDissent] = []
+    if winner == "tie":
+        return out
+    for s in scores:
+        loser_score = s.option_b_score if winner == option_a else s.option_a_score
+        winner_score = s.option_a_score if winner == option_a else s.option_b_score
+        loser = option_b if winner == option_a else option_a
+        if loser_score - winner_score >= 0.15:
+            out.append(
+                MatchDissent(
+                    role=f"criterion:{s.criterion}",
+                    counter_winner=loser,
+                    rationale=(
+                        f"On {s.criterion}, {loser} scored "
+                        f"{loser_score:.2f} vs winner's {winner_score:.2f}. "
+                        f"If this criterion were weighted higher, the verdict "
+                        f"would flip."
+                    ),
+                )
+            )
+    return out
+
+
+def _condorcet_winner(
+    options: list[str],
+    pairwise: dict[str, dict[str, str]],
+) -> str | None:
+    for o in options:
+        beats_all = True
+        for other in options:
+            if other == o:
+                continue
+            if pairwise.get(o, {}).get(other) != "win":
+                beats_all = False
+                break
+        if beats_all:
+            return o
+    return None
+
+
+def _borda_counts(matches: list[Match], options: list[str]) -> dict[str, int]:
+    counts: dict[str, int] = {o: 0 for o in options}
+    for m in matches:
+        if m.winner in counts:
+            counts[m.winner] += 1
+    return counts
+
+
+def _sensitivity_pivots(
+    options: list[str],
+    matches: list[Match],
+    criteria: list[tuple[str, float]],
+    current_winner: str,
+) -> list[dict[str, Any]]:
+    """For each criterion, ask: at what weight does the overall winner
+    change? Approximation: re-rank Borda counts under doubled weight on
+    that criterion, see if the new winner differs.
+
+    This is a synthetic mirror of "what would change my mind?"
+    """
+    pivots: list[dict[str, Any]] = []
+    for name, _ in criteria:
+        boosted_borda: dict[str, int] = {o: 0 for o in options}
+        for m in matches:
+            # Re-resolve with this criterion doubled.
+            new_diff = 0.0
+            new_w = 0.0
+            for s in m.scores:
+                w = s.weight * 2.0 if s.criterion == name else s.weight
+                new_diff += w * (s.option_a_score - s.option_b_score)
+                new_w += w
+            margin = new_diff / max(new_w, 0.001)
+            if abs(margin) < 0.02:
+                continue
+            new_winner = m.option_a if margin > 0 else m.option_b
+            boosted_borda[new_winner] += 1
+        new_overall = max(boosted_borda.items(), key=lambda kv: kv[1])[0]
+        if new_overall != current_winner:
+            pivots.append(
+                {
+                    "criterion": name,
+                    "current_winner": current_winner,
+                    "new_winner": new_overall,
+                    "explanation": (
+                        f"If {name!r} were weighted ~2x higher, the overall "
+                        f"winner would shift from {current_winner!r} to "
+                        f"{new_overall!r}."
+                    ),
+                }
+            )
+    return pivots
+
+
+# --- Run function ----------------------------------------------------------
+
+
+async def _run_tournament(args: Any, recorder: Any | None = None) -> None:
+    payload = getattr(args, "mode_payload", None) or {}
+    question = (payload.get("question") or "").strip() or (
+        "Acquire vs build vs partner for the new AI capability."
+    )
+    options = _parse_options(payload.get("options") or [])
+    if len(options) < 2:
+        # Demo-friendly fallback so the SPA always renders something.
+        options = ["acquire", "build", "partner"]
+    criteria = _parse_criteria(payload.get("criteria") or [])
+    if not criteria:
+        criteria = _seed_criteria_for_question(question)
+
+    started_at = time.time()
+    salt = hashlib.sha256(question.encode("utf-8")).hexdigest()[:16]
+
+    matches: list[Match] = []
+    pairwise: dict[str, dict[str, str]] = {o: {} for o in options}
+
+    for i, (a, b) in enumerate(combinations(options, 2), start=1):
+        scores, winner, margin = _resolve_match(a, b, criteria)
+        dissents = _match_dissents(scores, a, b, winner)
+        receipt_kid = hashlib.sha256(
+            f"match::{salt}::{a}::{b}".encode(),
+        ).hexdigest()[:24]
+        m = Match(
+            match_id=f"M-{i:03d}",
+            option_a=a,
+            option_b=b,
+            scores=scores,
+            winner=winner,
+            margin=margin,
+            receipt_kid=receipt_kid,
+            dissents=dissents,
+        )
+        matches.append(m)
+        if winner == "tie":
+            pairwise[a][b] = "tie"
+            pairwise[b][a] = "tie"
+        else:
+            loser = b if winner == a else a
+            pairwise[winner][loser] = "win"
+            pairwise[loser][winner] = "loss"
+
+    # Self-cells = "-"
+    for o in options:
+        pairwise[o][o] = "-"
+
+    borda = _borda_counts(matches, options)
+    winner_borda = max(borda.items(), key=lambda kv: kv[1])[0]
+    winner_condorcet = _condorcet_winner(options, pairwise)
+    sensitivity = _sensitivity_pivots(options, matches, criteria, winner_borda)
+
+    summary = TournamentSummary(
+        winner_condorcet=winner_condorcet,
+        winner_borda=winner_borda,
+        borda_counts=borda,
+        pairwise_table=pairwise,
+        sensitivity_pivots=sensitivity,
+        n_options=len(options),
+        n_criteria=len(criteria),
+    )
+
+    elapsed = time.time() - started_at
+    trace = {
+        "mode": "decision-tournament",
+        "started_at": started_at,
+        "elapsed_s": round(elapsed, 3),
+        "n_agents": len(options) + len(criteria),
+        "n_questions": len(matches),
+        "question": question,
+        "options": options,
+        "criteria": [{"name": n, "weight": w} for n, w in criteria],
+        "matches": [asdict(m) for m in matches],
+        "summary": asdict(summary),
+        "collective_iq": {
+            "score": round(
+                max(borda.values()) / max(len(matches), 1),
+                4,
+            ),
+        },
+    }
+
+    Path(args.trace).write_text(json.dumps(trace, indent=2, default=str))
+
+
+# --- Registration ----------------------------------------------------------
+
+SPEC = ModeSpec(
+    slug="decision-tournament",
+    label="Decision Tournament",
+    description=(
+        "Round-robin pairwise tournament across N options and weighted "
+        "criteria. Produces a Condorcet winner (when one exists), "
+        "Borda count ranking, and a sensitivity panel: 'if you weighted "
+        "criterion X higher, would the winner change?'"
+    ),
+    input_schema=INPUT_SCHEMA,
+    result_schema=RESULT_SCHEMA,
+    run_fn=_run_tournament,
+    uses_legacy_fields=False,
+    expected_roles=["scout", "sceptic", "synthesist", "mediator"],
+)
+
+
+register(SPEC)