hypermind 0.11.0__py3-none-any.whl

hypermind/consult.py

@@ -0,0 +1,493 @@
+"""ConsultResult and routing strategies.
+
+Routing strategies:
+  - "disagreement": route to the panel whose pairwise posterior
+    disagreement is maximal — well-defined without external prior, has
+    an information-theoretic interpretation (BALD-style).
+  - "calibration": route to historically best-calibrated agents.
+  - "random": uniform sample (sandbox/baseline).
+  - "stratified": stratify by reputation quantile to avoid mode collapse.
+"""
+
+from __future__ import annotations
+
+import math
+import random
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from hypermind.uncertainty import Uncertainty
+from hypermind.wire import Kid
+
+if False:  # TYPE_CHECKING
+    from hypermind.responders.structured import StructuredResponse
+
+RouteStrategyName = Literal["disagreement", "calibration", "random", "stratified"]
+RouteStrategy = RouteStrategyName | Callable[..., list[bytes]]
+
+
+@dataclass
+class PanelMember:
+    agent_id: bytes
+    weight: float
+    posterior: Uncertainty
+    route_reason: str
+    #: Optional structured reasoning captured by LLM responders (v0.6+).
+    #: Bare ``Uncertainty``-only responders leave this as ``None``.
+    structured: StructuredResponse | None = None
+    #: Namespace id (hex string) of the panel member's home namespace.
+    #: ``None`` for same-namespace members; set for cross-namespace members.
+    namespace_id: str | None = None
+    #: Reputation score read from the member's home namespace at consult
+    #: time. Displayed in the synthesis payload for transparency; never
+    #: silently merged into the calling namespace's reputation kernel.
+    foreign_reputation_snapshot: float | None = None
+
+
+@dataclass
+class CalibTruthSnapshot:
+    """Selection-bias trap detector (Wei-Chen Cycle 2 §4).
+
+    Under a healthy roadmap, calibration improves and truth-coverage
+    rises. The dangerous regime is "calibration appears to improve
+    while truth-coverage shrinks" — the system gets better only on
+    easy claims that resolve.
+    """
+
+    calibration_brier: float
+    truth_coverage_ratio: float
+    warning: Literal["healthy", "selection_bias", "insufficient_resolution"] | None = None
+
+    @classmethod
+    def from_metrics(
+        cls,
+        calibration_brier: float,
+        truth_coverage_ratio: float,
+        prev_calibration: float | None = None,
+        prev_coverage: float | None = None,
+    ) -> CalibTruthSnapshot:
+        warning: Literal["healthy", "selection_bias", "insufficient_resolution"] | None = None
+        if truth_coverage_ratio < 0.4:
+            warning = "insufficient_resolution"
+        elif (
+            prev_calibration is not None
+            and prev_coverage is not None
+            and calibration_brier < prev_calibration  # calibration improved
+            and truth_coverage_ratio < prev_coverage - 0.1  # but coverage shrank
+        ):
+            warning = "selection_bias"
+        else:
+            warning = "healthy"
+        return cls(
+            calibration_brier=calibration_brier,
+            truth_coverage_ratio=truth_coverage_ratio,
+            warning=warning,
+        )
+
+
+ARGUMENT_EDGE_KINDS = ("supports", "rebuts", "undercuts", "qualifies")
+"""Toulmin / IBIS argument edge kinds (ROADMAP §0.3.5).
+
+  * ``supports``  — adds positive evidence to the dst claim.
+  * ``rebuts``    — disputes the dst claim's truth.
+  * ``undercuts`` — disputes the *warrant* (chain of inference) without
+                    contradicting the dst directly.
+  * ``qualifies`` — narrows the dst's scope without rejecting it.
+"""
+
+ArgumentEdgeKind = Literal["supports", "rebuts", "undercuts", "qualifies"]
+
+
+@dataclass
+class ArgumentEdge:
+    src_kid: Kid
+    dst_kid: Kid
+    edge_type: Literal["elicits", "asserts", "rebuts", "contradicts", "aggregates", "settles"]
+    weight: float = 1.0
+    #: Toulmin/IBIS-shaped kind. Optional for back-compat; the closed
+    #: set is :data:`ARGUMENT_EDGE_KINDS`. ``None`` means "not yet
+    #: classified" — older receipts that pre-date v0.3.5 round-trip
+    #: without modification.
+    kind: ArgumentEdgeKind | None = None
+
+    def __post_init__(self) -> None:
+        if self.kind is not None and self.kind not in ARGUMENT_EDGE_KINDS:
+            raise ValueError(
+                f"unknown argument edge kind {self.kind!r}; valid kinds: {ARGUMENT_EDGE_KINDS}"
+            )
+
+
+@dataclass
+class ArgumentDAG:
+    edges: list[ArgumentEdge] = field(default_factory=list)
+
+    def summary(self) -> dict[str, int]:
+        """Return a ``{kind: count}`` summary of edge kinds.
+
+        Surfaces support+rebut conflict so callers can see at a glance
+        whether the DAG has internal tension.
+        """
+        out: dict[str, int] = {k: 0 for k in ARGUMENT_EDGE_KINDS}
+        for e in self.edges:
+            if e.kind is not None:
+                out[e.kind] = out.get(e.kind, 0) + 1
+        return out
+
+    def has_conflict(self) -> bool:
+        """True iff the DAG carries both supports and rebuts edges."""
+        s = self.summary()
+        return s.get("supports", 0) > 0 and s.get("rebuts", 0) > 0
+
+
+@dataclass
+class ConsultResult:
+    query: str
+    posterior: Uncertainty
+    panel: list[PanelMember]
+    argument_dag: ArgumentDAG
+    disagreement: float  # JS-divergence across panel posteriors
+    calibration_truth_axis: CalibTruthSnapshot
+    receipt_kid: Kid
+    panel_composition_hash: str
+    #: v0.6+ — list of structured reasoning records, one per panel member.
+    #: Empty when no LLM responder produced structured output.
+    structured_panel: list[StructuredResponse] = field(default_factory=list)
+    #: v0.6+ — full mixture of per-member posteriors (preserves dissent).
+    #: ``None`` when no panel members survived (shouldn't normally happen).
+    mixture: PosteriorMixture | None = None
+
+    @property
+    def is_high_disagreement(self) -> bool:
+        return self.disagreement > 0.5
+
+    def synthesize(
+        self,
+        *,
+        diversity_guard: Any | None = None,
+    ) -> dict[str, Any]:
+        """Return a synthesis payload, with T4-05 first-class diversity quorum.
+
+        When ``diversity_guard`` is supplied (a ``DiversityGuard``-shaped
+        object exposing ``check_quorum``), the payload carries
+        ``diversity_warning: bool`` indicating the quorum verdict and a
+        ``diversity_quorum`` block with the full result. Without a guard,
+        the payload omits these fields and behaviour is unchanged.
+        """
+        out: dict[str, Any] = {
+            "query": self.query,
+            "posterior_mean": self.posterior.mean(),
+            "panel_size": len(self.panel),
+            "disagreement": self.disagreement,
+            "panel_composition_hash": self.panel_composition_hash,
+        }
+        if diversity_guard is not None:
+            citations: list[list[bytes]] = []
+            for m in self.panel:
+                cs = getattr(m, "citations", None) or getattr(m, "parent_kids", None) or []
+                citations.append([bytes(c) for c in cs])
+
+                # Wrap citations in a member-shaped record.
+
+            class _M:
+                __slots__ = ("citations",)
+
+                def __init__(self, c: list[bytes]) -> None:
+                    self.citations = c
+
+            quorum = diversity_guard.check_quorum([_M(c) for c in citations])
+            out["diversity_warning"] = not quorum.passed
+            out["diversity_quorum"] = quorum.as_dict()
+        return out
+
+
+# ---- routing -----------------------------------------------------------
+
+
+def select_panel(
+    candidates: list[bytes],
+    panel_size: int,
+    *,
+    strategy: RouteStrategy,
+    posterior_estimate: Callable[[bytes], Uncertainty] | None = None,
+    reputation: Callable[[bytes], float] | None = None,
+    rng: random.Random | None = None,
+) -> list[bytes]:
+    """Choose a panel from candidates per the requested strategy."""
+    rng = rng or random.Random()
+    if not candidates:
+        return []
+    panel_size = min(panel_size, len(candidates))
+
+    if callable(strategy):
+        return list(strategy(candidates, panel_size))
+
+    if strategy == "random":
+        return rng.sample(candidates, panel_size)
+
+    if strategy == "calibration":
+        if reputation is None:
+            return rng.sample(candidates, panel_size)
+        return sorted(candidates, key=reputation, reverse=True)[:panel_size]
+
+    if strategy == "stratified":
+        if reputation is None:
+            return rng.sample(candidates, panel_size)
+        # Bucket by quantile, sample one from each bucket.
+        sorted_by_rep = sorted(candidates, key=reputation, reverse=True)
+        bucket_size = max(1, len(sorted_by_rep) // panel_size)
+        return [
+            sorted_by_rep[i * bucket_size]
+            for i in range(panel_size)
+            if i * bucket_size < len(sorted_by_rep)
+        ]
+
+    if strategy == "disagreement":
+        if posterior_estimate is None:
+            return rng.sample(candidates, panel_size)
+        # Greedy: pick first by reputation (or random); then add the
+        # candidate that maximises mean pairwise JS-divergence with the
+        # current panel.
+        chosen: list[bytes] = []
+        if reputation is not None:
+            seed = max(candidates, key=reputation)
+        else:
+            seed = rng.choice(candidates)
+        chosen.append(seed)
+        remaining = [c for c in candidates if c != seed]
+        while len(chosen) < panel_size and remaining:
+            best = max(
+                remaining,
+                key=lambda c: sum(
+                    _js_divergence(posterior_estimate(c), posterior_estimate(p)) for p in chosen
+                ),
+            )
+            chosen.append(best)
+            remaining.remove(best)
+        return chosen
+
+    raise ValueError(f"unknown route strategy {strategy!r}")
+
+
+# ---- aggregation -------------------------------------------------------
+
+
+def aggregate_panel(panel: list[PanelMember]) -> tuple[Uncertainty, float]:
+    """Reputation-weighted Beta aggregation + JS-divergence disagreement."""
+    if not panel:
+        raise ValueError("cannot aggregate empty panel")
+
+    # Weighted mean of Beta posteriors → Beta(weighted α, weighted β).
+    total_w = sum(p.weight for p in panel) or 1.0
+    alpha_sum, beta_sum = 0.0, 0.0
+    for p in panel:
+        if p.posterior.kind != "beta":
+            mean = p.posterior.mean()
+            alpha_sum += mean * p.weight
+            beta_sum += (1 - mean) * p.weight
+        else:
+            a, b = p.posterior.params
+            alpha_sum += a * (p.weight / total_w)
+            beta_sum += b * (p.weight / total_w)
+    aggregated = Uncertainty.beta(max(alpha_sum, 0.5), max(beta_sum, 0.5))
+
+    # Mean pairwise JS-divergence.
+    n = len(panel)
+    if n < 2:
+        return aggregated, 0.0
+    total_js = 0.0
+    pairs = 0
+    for i in range(n):
+        for j in range(i + 1, n):
+            total_js += _js_divergence(panel[i].posterior, panel[j].posterior)
+            pairs += 1
+    disagreement = total_js / max(pairs, 1)
+    return aggregated, max(0.0, min(disagreement, 1.0))
+
+
+# ---- v0.6 dissent preservation -----------------------------------------
+
+
+@dataclass(frozen=True)
+class PosteriorMixture:
+    """Weighted mixture of per-member Beta posteriors.
+
+    The aggregator collapses bimodal panels into a single Beta. The
+    mixture preserves the full panel distribution so callers can
+    surface minority views, escalate on high-disagreement, or compute
+    arbitrary functionals (e.g., 10th-percentile scenario).
+
+    ``components`` is sorted descending by weight; weights are normalised
+    to sum to 1.0.
+    """
+
+    components: tuple[tuple[float, Uncertainty], ...]
+    majority_threshold: float = 0.5
+
+    @property
+    def n_components(self) -> int:
+        return len(self.components)
+
+    def majority_view(self) -> Uncertainty | None:
+        """Return the highest-weight component's Uncertainty."""
+        if not self.components:
+            return None
+        return self.components[0][1]
+
+    def minority_views(self) -> list[tuple[float, Uncertainty]]:
+        """Components whose cumulative weight is below ``majority_threshold``.
+
+        Iterates in weight-descending order; once cumulative weight
+        exceeds the threshold, all *remaining* components are minority.
+        """
+        if not self.components:
+            return []
+        cumulative = 0.0
+        out: list[tuple[float, Uncertainty]] = []
+        majority_passed = False
+        for w, u in self.components:
+            cumulative += w
+            if not majority_passed:
+                if cumulative >= self.majority_threshold:
+                    majority_passed = True
+                continue
+            out.append((w, u))
+        return out
+
+    def to_dict(self) -> dict:
+        components_out = []
+        for w, u in self.components:
+            entry = {"weight": w, "posterior_mean": u.mean()}
+            if hasattr(u, "to_cbor"):
+                cbor = u.to_cbor()
+                # to_cbor returns a dict in this SDK; serialise as-is
+                entry["uncertainty"] = cbor if isinstance(cbor, dict) else None
+            components_out.append(entry)
+        return {
+            "n_components": self.n_components,
+            "components": components_out,
+            "majority_threshold": self.majority_threshold,
+        }
+
+
+def build_posterior_mixture(
+    panel: list[PanelMember],
+    *,
+    majority_threshold: float = 0.5,
+) -> PosteriorMixture:
+    """Build a :class:`PosteriorMixture` from panel members.
+
+    Weights are normalised to sum to 1.0; components sorted by weight
+    descending. Members with non-positive weight (rare, but possible
+    when reputation × calibration is exactly 0) get a tiny floor so
+    they're surfaced rather than silently dropped.
+    """
+    if not panel:
+        return PosteriorMixture(components=(), majority_threshold=majority_threshold)
+    raw = [(max(m.weight, 1e-9), m.posterior) for m in panel]
+    total = sum(w for w, _ in raw)
+    normalised = [(w / total, u) for w, u in raw]
+    normalised.sort(key=lambda x: x[0], reverse=True)
+    return PosteriorMixture(
+        components=tuple(normalised),
+        majority_threshold=majority_threshold,
+    )
+
+
+# ---- info-gain panel routing (ROADMAP §0.3.3) -------------------------
+
+
+def _bernoulli_entropy(p: float) -> float:
+    """Binary entropy in nats. Bounded; numerically stable at the edges."""
+    p = max(min(p, 1 - 1e-12), 1e-12)
+    return -p * math.log(p) - (1 - p) * math.log(1 - p)
+
+
+def _aggregate_mean(posteriors: list[Uncertainty], weights: list[float]) -> float:
+    if not posteriors:
+        return 0.5
+    total = sum(weights) or 1.0
+    return sum(p.mean() * w for p, w in zip(posteriors, weights, strict=False)) / total
+
+
+class InfoGainRouter:
+    """Greedy expected-info-gain panel selector.
+
+    Selects panel members maximising the *expected predictive entropy
+    reduction* about the claim's truth. Concretely, the router picks
+    the candidate whose addition to the running panel most reduces the
+    aggregated posterior's binary entropy — agents with more peaked
+    estimates (high reputation, sharp posteriors) drive entropy down
+    fast, while uncertain candidates expand the predictive support.
+
+    The router is pure-Python and stateless; tests can drive it with
+    arbitrary posterior estimators.
+    """
+
+    def __init__(
+        self,
+        posterior_estimate: Callable[[bytes], Uncertainty],
+        weight: Callable[[bytes], float] | None = None,
+    ) -> None:
+        self._posterior = posterior_estimate
+        self._weight = weight or (lambda _kid: 1.0)
+
+    def select(self, candidates: list[bytes], k: int) -> list[bytes]:
+        """Return the top-k candidates maximising expected info gain."""
+        if k <= 0 or not candidates:
+            return []
+        if k == 1:
+            # Single-pick: choose the candidate with the lowest
+            # individual posterior entropy (sharpest belief).
+            return [
+                min(
+                    candidates,
+                    key=lambda c: _bernoulli_entropy(self._posterior(c).mean()),
+                )
+            ]
+
+        chosen: list[bytes] = []
+        remaining = list(candidates)
+        while len(chosen) < k and remaining:
+            current_post = [self._posterior(c) for c in chosen]
+            current_w = [self._weight(c) for c in chosen]
+            current_mean = _aggregate_mean(current_post, current_w) if chosen else 0.5
+            current_entropy = _bernoulli_entropy(current_mean)
+
+            def _gain(
+                c: bytes,
+                _post: list = current_post,  # bind loop variable (B023)
+                _w: list = current_w,  # bind loop variable (B023)
+                _entropy: float = current_entropy,  # bind loop variable (B023)
+            ) -> float:
+                p = [*_post, self._posterior(c)]
+                w = [*_w, self._weight(c)]
+                new_mean = _aggregate_mean(p, w)
+                new_entropy = _bernoulli_entropy(new_mean)
+                # Expected info gain ≈ (_entropy - new_entropy) +
+                # epsilon * uncertainty_of_candidate so ties favour
+                # higher-uncertainty members (panel diversity).
+                cand_uncertainty = _bernoulli_entropy(self._posterior(c).mean())
+                return (_entropy - new_entropy) + 1e-3 * cand_uncertainty
+
+            best = max(remaining, key=_gain)
+            chosen.append(best)
+            remaining.remove(best)
+        return chosen
+
+
+def _js_divergence(a: Uncertainty, b: Uncertainty) -> float:
+    """Jensen-Shannon divergence between two Bernoulli means.
+
+    Bounded in [0, 1] when using log base 2; we use natural log and
+    rescale to [0, 1] dividing by ln(2).
+    """
+    p = max(min(a.mean(), 1 - 1e-9), 1e-9)
+    q = max(min(b.mean(), 1 - 1e-9), 1e-9)
+    m = 0.5 * (p + q)
+
+    def _kl(x: float, y: float) -> float:
+        return x * math.log(x / y) + (1 - x) * math.log((1 - x) / (1 - y))
+
+    js = 0.5 * _kl(p, m) + 0.5 * _kl(q, m)
+    return max(0.0, min(js / math.log(2), 1.0))

hypermind/consult_bias.py

@@ -0,0 +1,112 @@
+"""Selection-bias trap detector for consult panels (ROADMAP §0.3.6).
+
+Compares an actual panel's composition against the registered
+population distribution along one or more dimensions (e.g. ``org``,
+``topic_history``). KL-divergence above a configurable threshold
+flags the panel as biased.
+
+The detector is dimension-agnostic: callers pass a dict per panel
+member describing their attributes, plus an expected distribution per
+dimension. Any dimension that drifts beyond ``threshold`` produces a
+:class:`BiasFinding`.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+EPS = 1e-9
+DEFAULT_THRESHOLD = 0.5
+
+
+@dataclass(frozen=True)
+class BiasFinding:
+    dimension: str
+    kl_divergence: float
+    expected: dict[str, float]
+    observed: dict[str, float]
+    severity: str  # "warning" | "critical"
+
+
+@dataclass(frozen=True)
+class PanelMemberAttrs:
+    """Minimal panel-member descriptor for the bias detector.
+
+    Real panel members carry more state; this dataclass extracts only
+    the dimensional attributes the detector needs.
+    """
+
+    agent_id: bytes
+    attributes: Mapping[str, str]
+
+
+def _kl(p: Mapping[str, float], q: Mapping[str, float]) -> float:
+    """KL(P || Q) over the union of categories."""
+    keys = set(p) | set(q)
+    out = 0.0
+    for k in keys:
+        pk = max(p.get(k, 0.0), EPS)
+        qk = max(q.get(k, 0.0), EPS)
+        out += pk * math.log(pk / qk)
+    return out
+
+
+def _normalise(d: Mapping[str, float]) -> dict[str, float]:
+    total = sum(max(0.0, v) for v in d.values())
+    if total <= 0:
+        return {k: 0.0 for k in d}
+    return {k: max(0.0, v) / total for k, v in d.items()}
+
+
+def detect_selection_bias(
+    panel: list[PanelMemberAttrs],
+    population_stats: Mapping[str, Mapping[str, float]],
+    *,
+    threshold: float = DEFAULT_THRESHOLD,
+    critical_threshold: float = 1.5,
+) -> list[BiasFinding]:
+    """Compute per-dimension KL-divergence and emit findings above threshold.
+
+    Args:
+        panel: Actual panel members.
+        population_stats: ``{dimension: {category: expected_freq}}``.
+        threshold: KL-divergence above this emits a warning finding.
+        critical_threshold: KL-divergence above this escalates to
+            critical.
+
+    Returns:
+        Sorted list of :class:`BiasFinding`. Empty if the panel
+        composition is statistically indistinguishable from the
+        registered population on every dimension.
+    """
+    if not panel:
+        # Tiny / empty panel: no meaningful distribution comparison.
+        return []
+    findings: list[BiasFinding] = []
+    for dim, expected_raw in population_stats.items():
+        expected = _normalise(expected_raw)
+        observed_counts: dict[str, float] = {}
+        for m in panel:
+            v = m.attributes.get(dim)
+            if v is None:
+                continue
+            observed_counts[v] = observed_counts.get(v, 0.0) + 1.0
+        if not observed_counts:
+            continue
+        observed = _normalise(observed_counts)
+        kl = _kl(observed, expected)
+        if kl >= threshold:
+            severity = "critical" if kl >= critical_threshold else "warning"
+            findings.append(
+                BiasFinding(
+                    dimension=dim,
+                    kl_divergence=kl,
+                    expected=dict(expected),
+                    observed=observed,
+                    severity=severity,
+                )
+            )
+    findings.sort(key=lambda f: -f.kl_divergence)
+    return findings