hypermind 0.11.0__py3-none-any.whl

hypermind/eval/swarm_iq.py

@@ -0,0 +1,718 @@
+"""SwarmIQ — collective intelligence metrics.
+
+The five normative metrics from docs/spec/20-swarm-intelligence.md §20.1.
+
+The single most important number is ``wisdom_of_crowds_delta`` — when
+negative, the swarm consensus out-thinks its best individual member.
+That is the headline claim "world-best swarm intelligence" rests on.
+
+All metrics are pure functions over an immutable EvalSet. No agent
+mutation, no I/O, deterministic.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from hypermind.eval.calibration import brier_score
+
+
+@dataclass(frozen=True)
+class Prediction:
+    """A single agent's prediction on one question.
+
+    ``confidence`` is the agent's probability that the answer is True.
+    ``citations`` (optional) lets the diversity-payoff metric compute
+    panel Jaccard overlap.
+    """
+
+    agent_kid: bytes
+    question_id: str
+    confidence: float
+    citations: tuple[bytes, ...] = ()
+
+
+@dataclass(frozen=True)
+class GroundTruth:
+    question_id: str
+    outcome: float  # 0.0 or 1.0 in v0.9b; v1.x may admit fractional
+
+
+@dataclass
+class EvalSet:
+    """A frozen evaluation set for SwarmIQ scoring."""
+
+    predictions: list[Prediction]
+    truths: list[GroundTruth]
+    consensus_kind: str = "mean"  # "mean" | "weighted_mean"
+
+    def truth_map(self) -> dict[str, float]:
+        return {t.question_id: t.outcome for t in self.truths}
+
+    def per_agent(self) -> dict[bytes, list[Prediction]]:
+        out: dict[bytes, list[Prediction]] = {}
+        for p in self.predictions:
+            out.setdefault(bytes(p.agent_kid), []).append(p)
+        return out
+
+    def per_question(self) -> dict[str, list[Prediction]]:
+        out: dict[str, list[Prediction]] = {}
+        for p in self.predictions:
+            out.setdefault(p.question_id, []).append(p)
+        return out
+
+
+# ---------------------------------------------------------------------------
+# Core scoring
+# ---------------------------------------------------------------------------
+
+
+def consensus_confidence(
+    predictions: Sequence[Prediction],
+    weights: dict[bytes, float] | None = None,
+) -> float:
+    """Aggregate per-question predictions into a single consensus probability."""
+    if not predictions:
+        return 0.5
+    if weights:
+        total_w = 0.0
+        weighted = 0.0
+        for p in predictions:
+            w = weights.get(bytes(p.agent_kid), 1.0)
+            weighted += w * p.confidence
+            total_w += w
+        return weighted / total_w if total_w else 0.5
+    return sum(p.confidence for p in predictions) / len(predictions)
+
+
+def mean_brier_for_agent(eval_set: EvalSet, agent_kid: bytes) -> float | None:
+    truths = eval_set.truth_map()
+    rows = [p for p in eval_set.predictions if bytes(p.agent_kid) == bytes(agent_kid)]
+    if not rows:
+        return None
+    scored = [
+        brier_score(p.confidence, truths[p.question_id]) for p in rows if p.question_id in truths
+    ]
+    return sum(scored) / len(scored) if scored else None
+
+
+def mean_brier_for_consensus(
+    eval_set: EvalSet,
+    weights: dict[bytes, float] | None = None,
+) -> float:
+    truths = eval_set.truth_map()
+    rows: list[float] = []
+    for qid, preds in eval_set.per_question().items():
+        if qid not in truths:
+            continue
+        c = consensus_confidence(preds, weights=weights)
+        rows.append(brier_score(c, truths[qid]))
+    if not rows:
+        return float("nan")
+    return sum(rows) / len(rows)
+
+
+# ---------------------------------------------------------------------------
+# Reportable metrics
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SwarmIQReport:
+    """Stable JSON-serialisable report. CI compares against a baseline."""
+
+    namespace: str
+    n_agents: int
+    n_questions: int
+    wisdom_of_crowds_delta: float  # consensus_brier − best_member_brier
+    consensus_brier: float
+    best_member_brier: float
+    worst_member_brier: float
+    mean_member_brier: float
+    marginal_agent_value: dict[str, float] = field(default_factory=dict)
+    diversity_payoff_curve: list[tuple[float, float]] = field(default_factory=list)
+    time_to_truth_ticks: float | None = None
+    adversarial_robustness_score: float | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "namespace": self.namespace,
+            "n_agents": self.n_agents,
+            "n_questions": self.n_questions,
+            "wisdom_of_crowds_delta": self.wisdom_of_crowds_delta,
+            "consensus_brier": self.consensus_brier,
+            "best_member_brier": self.best_member_brier,
+            "worst_member_brier": self.worst_member_brier,
+            "mean_member_brier": self.mean_member_brier,
+            "marginal_agent_value": dict(self.marginal_agent_value),
+            "diversity_payoff_curve": list(self.diversity_payoff_curve),
+            "time_to_truth_ticks": self.time_to_truth_ticks,
+            "adversarial_robustness_score": self.adversarial_robustness_score,
+            "metadata": dict(self.metadata),
+        }
+
+    def beats_best_member(self) -> bool:
+        return self.wisdom_of_crowds_delta < 0
+
+
+def wisdom_of_crowds_delta(eval_set: EvalSet) -> tuple[float, float, float]:
+    """Returns (delta, consensus_brier, best_member_brier)."""
+    consensus = mean_brier_for_consensus(eval_set)
+    members = [mean_brier_for_agent(eval_set, kid) for kid in eval_set.per_agent()]
+    members = [m for m in members if m is not None]
+    if not members:
+        return float("nan"), consensus, float("nan")
+    best = min(members)
+    return (consensus - best), consensus, best
+
+
+def marginal_agent_value(eval_set: EvalSet) -> dict[bytes, float]:
+    """Per-agent: change in consensus Brier when this agent is dropped.
+
+    Positive value ⇒ dropping this agent makes consensus *worse*
+    (i.e. the agent contributes positive value).
+    """
+    base = mean_brier_for_consensus(eval_set)
+    out: dict[bytes, float] = {}
+    for kid in eval_set.per_agent():
+        held_out = EvalSet(
+            predictions=[p for p in eval_set.predictions if bytes(p.agent_kid) != bytes(kid)],
+            truths=eval_set.truths,
+            consensus_kind=eval_set.consensus_kind,
+        )
+        if not held_out.predictions:
+            continue
+        delta = mean_brier_for_consensus(held_out) - base
+        out[bytes(kid)] = delta
+    return out
+
+
+def diversity_payoff_curve(
+    eval_set: EvalSet,
+    bin_count: int = 10,
+) -> list[tuple[float, float]]:
+    """Per-question (mean panel Jaccard, consensus Brier).
+
+    Bin questions by their panel's mean pairwise Jaccard overlap;
+    return one (jaccard_bin_centre, mean_consensus_brier) per non-empty bin.
+    """
+    truths = eval_set.truth_map()
+    samples: list[tuple[float, float]] = []
+    for qid, preds in eval_set.per_question().items():
+        if qid not in truths:
+            continue
+        c = consensus_confidence(preds)
+        b = brier_score(c, truths[qid])
+        j = _mean_pairwise_jaccard([set(p.citations) for p in preds])
+        samples.append((j, b))
+    if not samples:
+        return []
+    bins: list[list[float]] = [[] for _ in range(bin_count)]
+    for j, b in samples:
+        idx = min(bin_count - 1, max(0, int(j * bin_count)))
+        bins[idx].append(b)
+    out: list[tuple[float, float]] = []
+    for i, bucket in enumerate(bins):
+        if not bucket:
+            continue
+        centre = (i + 0.5) / bin_count
+        out.append((centre, sum(bucket) / len(bucket)))
+    return out
+
+
+def adversarial_robustness_score(
+    eval_set: EvalSet,
+    *,
+    byzantine_fraction: float = 0.2,
+    seed: int = 42,
+) -> float:
+    """Consensus Brier degradation when a fraction of agents flip predictions.
+
+    Returns ``Brier(byzantine) − Brier(honest)``. Lower (closer to 0) is
+    more robust. Pure deterministic — picks byzantine agents by seeded
+    sampling from the sorted-kid list. Identical seed ⇒ identical
+    byzantine set.
+    """
+    import random as _random
+
+    rng = _random.Random(seed)
+    base = mean_brier_for_consensus(eval_set)
+    agents = sorted(eval_set.per_agent(), key=bytes)
+    if not agents:
+        return 0.0
+    n_byz = max(1, round(byzantine_fraction * len(agents)))
+    byzantine = set(rng.sample(agents, n_byz))
+
+    poisoned: list[Prediction] = []
+    for p in eval_set.predictions:
+        if bytes(p.agent_kid) in byzantine:
+            poisoned.append(
+                Prediction(
+                    agent_kid=p.agent_kid,
+                    question_id=p.question_id,
+                    confidence=1.0 - p.confidence,
+                    citations=p.citations,
+                )
+            )
+        else:
+            poisoned.append(p)
+    poisoned_set = EvalSet(
+        predictions=poisoned,
+        truths=eval_set.truths,
+        consensus_kind=eval_set.consensus_kind,
+    )
+    return mean_brier_for_consensus(poisoned_set) - base
+
+
+def time_to_truth_ticks(claim_to_resolution: Iterable[tuple[int, int]]) -> float | None:
+    """Average HLC-tick distance from first claim to oracle resolution.
+
+    Callers must supply (first_claim_hlc_ms, oracle_resolution_hlc_ms) pairs.
+    The simlab trace currently does not carry HLC timestamps inside
+    deliberation_records or oracle_resolutions — wiring that through (e.g.
+    `hlc_ms` on each round + on each oracle resolution) is a prerequisite
+    for trace-driven population. Returns None on empty input.
+    """
+    deltas = [r - c for c, r in claim_to_resolution if r >= c]
+    if not deltas:
+        return None
+    return sum(deltas) / len(deltas)
+
+
+# ---------------------------------------------------------------------------
+# Top-level scorer
+# ---------------------------------------------------------------------------
+
+
+def score(
+    eval_set: EvalSet,
+    *,
+    namespace: str = "default",
+    claim_to_resolution_ticks: Iterable[tuple[int, int]] = (),
+    byzantine_fraction: float = 0.2,
+) -> SwarmIQReport:
+    """Compute the full SwarmIQ report on an EvalSet."""
+    delta, consensus, best = wisdom_of_crowds_delta(eval_set)
+    members = [
+        m
+        for m in (mean_brier_for_agent(eval_set, kid) for kid in eval_set.per_agent())
+        if m is not None
+    ]
+    worst = max(members) if members else float("nan")
+    mean = sum(members) / len(members) if members else float("nan")
+    mav = marginal_agent_value(eval_set)
+    return SwarmIQReport(
+        namespace=namespace,
+        n_agents=len(eval_set.per_agent()),
+        n_questions=len(eval_set.per_question()),
+        wisdom_of_crowds_delta=delta,
+        consensus_brier=consensus,
+        best_member_brier=best,
+        worst_member_brier=worst,
+        mean_member_brier=mean,
+        marginal_agent_value={k.hex(): v for k, v in mav.items()},
+        diversity_payoff_curve=diversity_payoff_curve(eval_set),
+        time_to_truth_ticks=time_to_truth_ticks(claim_to_resolution_ticks),
+        adversarial_robustness_score=adversarial_robustness_score(
+            eval_set, byzantine_fraction=byzantine_fraction
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+# ---------------------------------------------------------------------------
+# Effective Information Gain per Question (EIG/Q) — v0.10
+# ---------------------------------------------------------------------------
+#
+# Replaces the legacy ``CollectiveIQ.score`` (a weighted hodgepodge with
+# no common units). EIG/Q measures realised information per question in
+# bits, derived purely from fields already in ``trace.json``:
+#   - panel_records[q].mean_confidence (final consensus)
+#   - panel_records[q].ground_truth (oracle outcome, when present)
+#   - deliberation_records[q].rounds[0].mean (round-0 starting confidence)
+#
+# Formula (Pinsker upper-bound on residual entropy):
+#
+#   EIG/Q = (1/Q) · Σ_q [ H_b(p̄_q^{round 0}) − 4·Brier(p̄_q^{final}, y_q) ]
+#
+# where H_b(p) = -p log2(p) - (1-p) log2(1-p) is the binary entropy.
+#
+# Properties:
+#   - Goes UP when the swarm started uncertain (high H_0) and ended close
+#     to truth (low Brier) — the only state that should count as "smarter".
+#   - Goes NEGATIVE when the swarm ended confidently wrong (4·Brier > H_0).
+#     This is the failure mode the legacy CIQ score *rewards* and EIG/Q
+#     correctly penalises.
+#   - Strictly proper, units in bits, no arbitrary weights.
+
+
+def _bernoulli_entropy_bits(p: float) -> float:
+    """Binary entropy in bits, clamped to [0, 1] for numerical stability."""
+    import math
+
+    p = max(0.0, min(1.0, float(p)))
+    if p <= 0.0 or p >= 1.0:
+        return 0.0
+    return -(p * math.log2(p) + (1.0 - p) * math.log2(1.0 - p))
+
+
+def effective_information_gain_per_question(
+    panel_records: Sequence[dict[str, Any]],
+    deliberation_records: Sequence[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    """Compute EIG/Q from trace-shaped panel + deliberation records.
+
+    Each ``panel_records[i]`` should carry ``mean_confidence`` (final) and
+    optionally ``ground_truth`` (binary 0.0/1.0). When deliberation rounds
+    are available, ``deliberation_records[i].rounds[0].mean`` provides the
+    round-0 starting confidence; otherwise we fall back to a 0.5 prior
+    (which gives H_0 = 1.0 bit — the maximum-entropy assumption).
+
+    Returns a dict with::
+
+        {
+            "eig_per_q": [<bits>, ...],   # one float per panel_record (NaN when no ground_truth)
+            "eig_mean": <float>,           # mean over questions with ground_truth, NaN if none
+            "baseline_round0_h": [<bits>, ...],  # the H_0 we used per q
+            "n_scored": <int>,             # questions that had ground_truth + were scored
+        }
+    """
+    deliberation_records = list(deliberation_records or [])
+    # Index deliberation by query string (the join key panel_records uses).
+    delib_by_query: dict[str, dict[str, Any]] = {}
+    for d in deliberation_records:
+        q = d.get("query")
+        if isinstance(q, str):
+            delib_by_query[q] = d
+
+    eig_per_q: list[float] = []
+    h0_per_q: list[float] = []
+    scored: list[float] = []
+
+    for rec in panel_records:
+        final = rec.get("mean_confidence")
+        gt = rec.get("ground_truth")
+        query = rec.get("query")
+
+        # Round-0 mean: prefer deliberation R0; fall back to first round
+        # mean on this rec if present; else 0.5 (max entropy).
+        h0_p: float = 0.5
+        delib = delib_by_query.get(query) if isinstance(query, str) else None
+        if delib:
+            rounds = delib.get("rounds") or []
+            if rounds:
+                first = rounds[0]
+                m = first.get("mean")
+                if isinstance(m, (int, float)):
+                    h0_p = float(m)
+        h0 = _bernoulli_entropy_bits(h0_p)
+        h0_per_q.append(h0)
+
+        # Need final confidence + ground truth to compute realised gain.
+        if final is None or gt is None:
+            eig_per_q.append(float("nan"))
+            continue
+        try:
+            f = float(final)
+            y = float(gt)
+        except (TypeError, ValueError):
+            eig_per_q.append(float("nan"))
+            continue
+        # Pinsker upper bound: 4·Brier ≥ H(post|truth) in bits (within a
+        # constant factor that we absorb into the bound).
+        residual_h_bound = 4.0 * brier_score(f, y)
+        eig = h0 - residual_h_bound
+        eig_per_q.append(eig)
+        scored.append(eig)
+
+    eig_mean = (sum(scored) / len(scored)) if scored else float("nan")
+    return {
+        "eig_per_q": eig_per_q,
+        "eig_mean": eig_mean,
+        "baseline_round0_h": h0_per_q,
+        "n_scored": len(scored),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Role recommendations
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class RoleAdjustment:
+    """A recommended role change for one agent, with rationale."""
+
+    agent_kid: str
+    current_role: str | None
+    recommended_role: str
+    confidence: float
+    trigger: str
+    reason: str
+
+
+class SwarmIQ:
+    """Stateful wrapper around an EvalSet that adds role-recommendation logic.
+
+    Usage::
+
+        siq = SwarmIQ(eval_set, roles={"<kid_hex>": "Scout", ...})
+        adjustments = siq.recommend()
+
+    ``roles`` maps agent_kid hex-string → current role string (or None).
+    If omitted, all agents are treated as role-less.
+
+    ``recommend()`` returns an empty list when there is insufficient data
+    (< 3 agents with scored predictions, or < 3 oracle resolutions).
+    """
+
+    # Minimum data thresholds below which the analysis is unreliable.
+    _MIN_AGENTS = 3
+    _MIN_RESOLUTIONS = 3
+
+    def __init__(
+        self,
+        eval_set: EvalSet,
+        *,
+        roles: dict[str, str | None] | None = None,
+    ) -> None:
+        self._eval_set = eval_set
+        self._roles: dict[str, str | None] = dict(roles or {})
+
+    def _agent_brier(self) -> dict[bytes, float]:
+        out: dict[bytes, float] = {}
+        for kid in self._eval_set.per_agent():
+            b = mean_brier_for_agent(self._eval_set, kid)
+            if b is not None:
+                out[kid] = b
+        return out
+
+    def _mav(self) -> dict[bytes, float]:
+        return marginal_agent_value(self._eval_set)
+
+    def recommend(self) -> list[RoleAdjustment]:
+        """Return role-change recommendations based on swarm performance metrics.
+
+        Trigger checks applied in order (first match wins per agent):
+
+        1. ``HIGH_BRIER_GENERALIST``: agent Brier ≥ median + 0.10 and no
+           current role → recommend ``Sceptic``.
+        2. ``POSITIVE_MAV_UNDERUSED``: marginal agent value ≥ 0.05 and no
+           current role → recommend ``Scout``.
+        3. ``NEGATIVE_MAV_DRAG``: marginal agent value ≤ -0.03 and current
+           role is ``Scout`` → recommend ``Sceptic``.
+
+        Confidence = 0.6 + min(0.3, |metric_delta| * 2). Only adjustments
+        with confidence ≥ 0.3 are emitted.
+        """
+        agent_briers = self._agent_brier()
+        scored_agents = list(agent_briers.keys())
+
+        # Insufficient data guard.
+        if len(scored_agents) < self._MIN_AGENTS:
+            return []
+        n_resolved = len(self._eval_set.truths)
+        if n_resolved < self._MIN_RESOLUTIONS:
+            return []
+
+        brier_values = list(agent_briers.values())
+        sorted_briers = sorted(brier_values)
+        mid = len(sorted_briers) // 2
+        if len(sorted_briers) % 2 == 1:
+            median_brier = sorted_briers[mid]
+        else:
+            median_brier = (sorted_briers[mid - 1] + sorted_briers[mid]) / 2.0
+
+        mav_map = self._mav()
+        adjustments: list[RoleAdjustment] = []
+
+        for kid in scored_agents:
+            kid_hex = kid.hex()
+            current_role = self._roles.get(kid_hex)
+
+            brier = agent_briers[kid]
+            mav_val = mav_map.get(kid, 0.0)
+
+            # --- Trigger 1: HIGH_BRIER_GENERALIST ---
+            brier_excess = brier - (median_brier + 0.10)
+            if brier_excess >= 0 and current_role is None:
+                delta = abs(brier_excess)
+                confidence = 0.6 + min(0.3, delta * 2)
+                if confidence >= 0.3:
+                    adjustments.append(
+                        RoleAdjustment(
+                            agent_kid=kid_hex,
+                            current_role=current_role,
+                            recommended_role="Sceptic",
+                            confidence=round(confidence, 6),
+                            trigger="HIGH_BRIER_GENERALIST",
+                            reason=(
+                                f"Brier {brier:.4f} ≥ swarm median "
+                                f"{median_brier:.4f} + 0.10; agent may "
+                                "benefit from a sceptic framing to reduce overconfidence."
+                            ),
+                        )
+                    )
+                continue
+
+            # --- Trigger 2: POSITIVE_MAV_UNDERUSED ---
+            if mav_val >= 0.05 and current_role is None:
+                delta = abs(mav_val)
+                confidence = 0.6 + min(0.3, delta * 2)
+                if confidence >= 0.3:
+                    adjustments.append(
+                        RoleAdjustment(
+                            agent_kid=kid_hex,
+                            current_role=current_role,
+                            recommended_role="Scout",
+                            confidence=round(confidence, 6),
+                            trigger="POSITIVE_MAV_UNDERUSED",
+                            reason=(
+                                f"Marginal agent value {mav_val:.4f} ≥ 0.05; "
+                                "agent contributes positively to consensus and "
+                                "should be formalised as a Scout."
+                            ),
+                        )
+                    )
+                continue
+
+            # --- Trigger 3: NEGATIVE_MAV_DRAG ---
+            if mav_val <= -0.03 and current_role == "Scout":
+                delta = abs(mav_val)
+                confidence = 0.6 + min(0.3, delta * 2)
+                if confidence >= 0.3:
+                    adjustments.append(
+                        RoleAdjustment(
+                            agent_kid=kid_hex,
+                            current_role=current_role,
+                            recommended_role="Sceptic",
+                            confidence=round(confidence, 6),
+                            trigger="NEGATIVE_MAV_DRAG",
+                            reason=(
+                                f"Marginal agent value {mav_val:.4f} ≤ -0.03 "
+                                "despite Scout role; agent is degrading swarm "
+                                "consensus and should switch to Sceptic."
+                            ),
+                        )
+                    )
+
+        return adjustments
+
+
+@dataclass(frozen=True)
+class ClusterScorecard:
+    """Cluster-level SwarmIQ scorecard (T6-07).
+
+    Aggregates diversity, coverage and calibration across a list of
+    agents — used by operators running multi-host federations who need a
+    single number per cluster (rather than per-agent) to chart over time.
+
+    * ``diversity`` — 1 − mean pairwise Jaccard over per-agent answered-
+      question sets. 1.0 means agents probe disjoint slices of the
+      question space; 0.0 means every agent answers the same questions.
+    * ``coverage`` — fraction of resolved questions for which at least
+      one agent in the cluster published a prediction.
+    * ``calibration`` — 1 − mean Brier across all (agent, question)
+      pairs that have an oracle truth. Higher = better calibrated.
+    * ``n_agents`` / ``n_questions_resolved`` — sample-size context so
+      operators can spot under-powered scorecards.
+    """
+
+    n_agents: int
+    n_questions_resolved: int
+    diversity: float
+    coverage: float
+    calibration: float
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "n_agents": self.n_agents,
+            "n_questions_resolved": self.n_questions_resolved,
+            "diversity": self.diversity,
+            "coverage": self.coverage,
+            "calibration": self.calibration,
+        }
+
+
+def _cluster_score_impl(eval_set: EvalSet, agent_kids: Sequence[bytes]) -> ClusterScorecard:
+    kid_set = {bytes(k) for k in agent_kids}
+    if not kid_set:
+        return ClusterScorecard(0, 0, 0.0, 0.0, 0.0)
+
+    truth_map = eval_set.truth_map()  # str question_id → 0/1 outcome
+    n_resolved = len(truth_map)
+
+    # Per-agent answered-question sets, restricted to the cluster.
+    per_agent = eval_set.per_agent()  # mapping kid → list[Prediction]
+    answered_sets: list[set[str]] = []
+    answered_any: set[str] = set()
+    brier_sum = 0.0
+    brier_n = 0
+    for kid in kid_set:
+        preds = per_agent.get(kid, [])
+        qids = {p.question_id for p in preds}
+        answered_sets.append(qids)
+        answered_any |= qids
+        for p in preds:
+            truth = truth_map.get(p.question_id)
+            if truth is None:
+                continue
+            outcome = float(truth)
+            brier_sum += (p.confidence - outcome) ** 2
+            brier_n += 1
+
+    # Reuse the helper defined further down in this module via name lookup.
+    diversity = 1.0 - _mean_pairwise_jaccard(answered_sets)  # type: ignore[arg-type]
+    coverage = len(answered_any & set(truth_map.keys())) / n_resolved if n_resolved else 0.0
+    calibration = 1.0 - (brier_sum / brier_n) if brier_n else 0.0
+    return ClusterScorecard(
+        n_agents=len(kid_set),
+        n_questions_resolved=n_resolved,
+        diversity=round(diversity, 6),
+        coverage=round(coverage, 6),
+        calibration=round(calibration, 6),
+    )
+
+
+def _swarmiq_cluster_score(self: SwarmIQ, agents: Sequence[Any]) -> ClusterScorecard:
+    """Return a :class:`ClusterScorecard` aggregating ``agents`` (T6-07).
+
+    ``agents`` accepts either raw kid bytes or any object with a ``.kid``
+    attribute (e.g. :class:`HyperMindAgent`).
+    """
+    kids: list[bytes] = []
+    for a in agents:
+        if isinstance(a, (bytes, bytearray)):
+            kids.append(bytes(a))
+        elif hasattr(a, "kid"):
+            kids.append(bytes(a.kid))
+        else:
+            raise TypeError(f"cluster_score: cannot extract kid from {type(a)!r}")
+    return _cluster_score_impl(self._eval_set, kids)
+
+
+SwarmIQ.cluster_score = _swarmiq_cluster_score  # type: ignore[attr-defined]
+
+
+def _mean_pairwise_jaccard(sets: Sequence[set[bytes]]) -> float:
+    sets = [s for s in sets if s]
+    if len(sets) < 2:
+        return 0.0
+    total = 0.0
+    n = 0
+    for i in range(len(sets)):
+        for j in range(i + 1, len(sets)):
+            a, b = sets[i], sets[j]
+            union = a | b
+            if not union:
+                continue
+            total += len(a & b) / len(union)
+            n += 1
+    return total / n if n else 0.0