hypermind 0.11.0__py3-none-any.whl

hypermind/mind/active.py

@@ -0,0 +1,234 @@
+"""Active learning — pick the *next best question* to ask the swarm.
+
+Information-gain planning, curriculum scheduling, anti-herding.
+
+Spec: docs/spec/20-swarm-intelligence.md §20.3.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+# ---------------------------------------------------------------------------
+# Information-gain planner
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class CandidateQuestion:
+    qid: str
+    topic: str
+    expected_posterior: float  # current swarm posterior estimate
+    cost: float = 1.0  # relative cost to consult (time, $, etc.)
+
+
+@dataclass
+class InformationGainPlanner:
+    """Pick the question that maximally narrows expected entropy.
+
+    Score = (current_entropy − expected_post_entropy) / cost.
+    The "expected post-entropy" is approximated by assuming the consult
+    will sharpen the posterior toward 0 or 1 with probability equal to
+    the current estimate.
+    """
+
+    sharpening: float = 0.5  # how much a consult shrinks distance to 0/1
+
+    def score_question(self, q: CandidateQuestion) -> float:
+        h_before = _bernoulli_entropy(q.expected_posterior)
+        # Two outcomes weighted by their current probability.
+        p = q.expected_posterior
+        post_yes = p + (1 - p) * self.sharpening
+        post_no = p * (1 - self.sharpening)
+        h_after = p * _bernoulli_entropy(post_yes) + (1 - p) * _bernoulli_entropy(post_no)
+        gain = max(0.0, h_before - h_after)
+        return gain / max(q.cost, 1e-6)
+
+    def pick(self, candidates: Sequence[CandidateQuestion]) -> CandidateQuestion | None:
+        if not candidates:
+            return None
+        ranked = sorted(candidates, key=self.score_question, reverse=True)
+        return ranked[0]
+
+    def rank(self, candidates: Sequence[CandidateQuestion]) -> list[CandidateQuestion]:
+        return sorted(candidates, key=self.score_question, reverse=True)
+
+    # ---- T4-06 multi-step planner --------------------------------------
+
+    def plan_multi_step(
+        self,
+        candidates: Sequence[CandidateQuestion],
+        *,
+        horizon: int = 3,
+        beam_width: int = 4,
+    ) -> list[CandidateQuestion]:
+        """Beam search over question sequences.
+
+        Returns up to ``horizon`` distinct candidates whose chained
+        sharpening maximises total expected entropy reduction. Each step
+        propagates the *post-yes* / *post-no* posterior estimates so the
+        next step's expected information gain is computed against the
+        sharpened estimate rather than the original prior.
+
+        For ``horizon=1`` the result is identical to ``[pick(candidates)]``.
+        """
+        if horizon <= 0 or not candidates:
+            return []
+        # Each beam state: (cumulative_gain, [chosen], remaining_candidates,
+        # rolling posterior estimate per qid).
+        Beam = tuple[float, list[CandidateQuestion], list[CandidateQuestion]]
+        beams: list[Beam] = [(0.0, [], list(candidates))]
+        for _ in range(horizon):
+            next_beams: list[Beam] = []
+            for cum_gain, chosen, remaining in beams:
+                if not remaining:
+                    next_beams.append((cum_gain, chosen, remaining))
+                    continue
+                # Score every remaining candidate against the rolling state.
+                # Sharpen estimates of *other* candidates by this candidate's
+                # sharpening factor so beam search sees diminishing returns.
+                for q in remaining:
+                    gain = self.score_question(q)
+                    new_chosen = [*chosen, q]
+                    sharpened: list[CandidateQuestion] = []
+                    for r in remaining:
+                        if r.qid == q.qid:
+                            continue
+                        # Move r's expected_posterior closer to the boundary
+                        # determined by q's expected_posterior — shared topic
+                        # questions interfere; cross-topic ones do not.
+                        if r.topic == q.topic:
+                            new_p = r.expected_posterior * (
+                                1 - self.sharpening * 0.5
+                            ) + q.expected_posterior * (self.sharpening * 0.5)
+                        else:
+                            new_p = r.expected_posterior
+                        sharpened.append(
+                            CandidateQuestion(
+                                qid=r.qid,
+                                topic=r.topic,
+                                expected_posterior=new_p,
+                                cost=r.cost,
+                            )
+                        )
+                    next_beams.append((cum_gain + gain, new_chosen, sharpened))
+            # Prune to top beam_width by cumulative gain.
+            next_beams.sort(key=lambda b: b[0], reverse=True)
+            beams = next_beams[:beam_width]
+            if not beams:
+                break
+        if not beams:
+            return []
+        best = max(beams, key=lambda b: b[0])
+        return best[1]
+
+
+# ---------------------------------------------------------------------------
+# Curriculum scheduler
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class AgentSnapshot:
+    kid: bytes
+    brier: float  # lower = better calibrated
+    n_observations: int
+
+
+@dataclass(frozen=True)
+class GradedQuestion:
+    qid: str
+    difficulty: float  # 0 = trivial, 1 = hardest
+
+
+@dataclass
+class CurriculumScheduler:
+    """Match agents to questions by difficulty.
+
+    Higher-Brier (worse) agents get easier questions; lower-Brier (better)
+    agents get harder ones. This is the active-learning mirror of the
+    classroom: practise on what you can almost do.
+    """
+
+    target_match_strength: float = 1.0  # higher → tighter matching
+
+    def assign(
+        self,
+        agents: Sequence[AgentSnapshot],
+        questions: Sequence[GradedQuestion],
+    ) -> dict[bytes, list[str]]:
+        if not agents or not questions:
+            return {}
+        # Normalise difficulty and brier into [0, 1].
+        max_b = max((a.brier for a in agents), default=1.0) or 1.0
+        max_d = max((q.difficulty for q in questions), default=1.0) or 1.0
+        out: dict[bytes, list[str]] = {bytes(a.kid): [] for a in agents}
+        for q in questions:
+            target = q.difficulty / max_d
+            best: tuple[float, AgentSnapshot] | None = None
+            for a in agents:
+                # better calibration (low brier) → assign harder questions.
+                ideal = 1.0 - (a.brier / max_b)
+                gap = abs(ideal - target)
+                if best is None or gap < best[0]:
+                    best = (gap, a)
+            if best is not None:
+                out[bytes(best[1].kid)].append(q.qid)
+        return out
+
+
+# ---------------------------------------------------------------------------
+# Anti-herding trigger
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class AntiHerdingTrigger:
+    """Surface minority signal when consensus is suspiciously tight.
+
+    If the panel posterior stdev drops below ``stdev_floor`` AND no
+    DissentRecord has been observed in the last ``window`` ticks, the
+    trigger asks the *most-disagreeing* candidate available — explicitly
+    seeking out a hold-out posterior to break the herd.
+    """
+
+    stdev_floor: float = 0.05
+    window_ticks: int = 16
+
+    def should_trigger(
+        self,
+        *,
+        recent_posteriors: Sequence[float],
+        ticks_since_last_dissent: int,
+    ) -> bool:
+        if len(recent_posteriors) < 3:
+            return False
+        mean = sum(recent_posteriors) / len(recent_posteriors)
+        var = sum((p - mean) ** 2 for p in recent_posteriors) / len(recent_posteriors)
+        std = math.sqrt(var)
+        return std < self.stdev_floor and ticks_since_last_dissent >= self.window_ticks
+
+    def pick_outlier(
+        self,
+        candidates: Sequence[tuple[bytes, float]],
+        *,
+        consensus_posterior: float,
+    ) -> bytes | None:
+        """From `(kid, posterior)` candidates, pick the one furthest from consensus."""
+        if not candidates:
+            return None
+        ranked = sorted(candidates, key=lambda kv: abs(kv[1] - consensus_posterior), reverse=True)
+        return bytes(ranked[0][0])
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _bernoulli_entropy(p: float) -> float:
+    eps = 1e-9
+    p = min(max(p, eps), 1.0 - eps)
+    return -(p * math.log(p, 2) + (1 - p) * math.log(1 - p, 2))

hypermind/mind/belief.py

@@ -0,0 +1,369 @@
+"""Belief state + Theory of Mind (T4 / spec §21).
+
+A belief is a per-(subject_kid, topic, proposition_hash) Beta posterior
+together with the evidence kids that justify it and the HLC at which
+the belief was last revised. Belief revision follows AGM postulates:
+
+    success       — after revising by ϕ, ϕ is in the belief set
+    inclusion     — revising by ϕ never adds *unrelated* propositions
+    vacuity       — if ¬ϕ is not in the belief set, expansion suffices
+    extensionality— logically equivalent ϕ, ψ produce equal revisions
+
+A *contradiction* (revising by ¬ϕ when ϕ is currently held with high
+posterior) does NOT crash — it forks the belief into the fork log
+(mirroring SwarmMemory's CRDT pattern). Both branches remain queryable
+via :meth:`BeliefStore.snapshot` until oracle resolution decides one.
+
+Theory of mind layers a second BeliefStore *per peer*: "what do I think
+peer P believes about topic T?" The peer's signed claims update the
+projection; the agent's deliberator uses the projection to weight goals
+that require peer cooperation.
+
+Spec banner: Original. Reuses `WorldModel` Protocol from world_model.py
+and the Beta-posterior shape from `knowledge/reputation.py`.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import time
+import uuid
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Any
+
+import cbor2
+
+_log = logging.getLogger(__name__)
+
+
+__all__ = [
+    "BeliefRecord",
+    "BeliefRevisionError",
+    "BeliefStore",
+    "TheoryOfMind",
+    "proposition_hash",
+]
+
+
+# ---------------------------------------------------------------------------
+# Records
+# ---------------------------------------------------------------------------
+
+
+def proposition_hash(proposition: bytes) -> bytes:
+    """Domain-tagged 32-byte hash of a CBOR-canonical proposition."""
+    return hashlib.sha256(b"hm:belief-prop:v1\x00" + bytes(proposition)).digest()
+
+
+@dataclass(frozen=True)
+class BeliefRecord:
+    """A signed (logically; signing is the caller's responsibility) belief.
+
+    The record is a value object; signing happens at publication time
+    (the caller wraps a BeliefRecord into a SignedStatement when emitting
+    onto the wire). The MUST clauses in §21 are enforced at *publication*
+    boundaries — the record itself is a pure data shape.
+    """
+
+    subject_kid: bytes  #: whose belief
+    topic: str
+    proposition: bytes  #: CBOR-canonical encoding of the asserted proposition
+    alpha: float = 1.0  #: Beta posterior α
+    beta: float = 1.0  #: Beta posterior β
+    evidence_kids: tuple[bytes, ...] = ()  #: supporting claim kids
+    hlc_ms: int = 0  #: hybrid logical clock (logical_ms component)
+    revision_id: str = field(default_factory=lambda: uuid.uuid4().hex)
+
+    @property
+    def proposition_hash(self) -> bytes:
+        return proposition_hash(self.proposition)
+
+    @property
+    def posterior_mean(self) -> float:
+        s = self.alpha + self.beta
+        return self.alpha / s if s > 0 else 0.5
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "subject_kid": self.subject_kid.hex(),
+            "topic": self.topic,
+            "proposition_hash": self.proposition_hash.hex(),
+            "alpha": self.alpha,
+            "beta": self.beta,
+            "evidence_kids": [k.hex() for k in self.evidence_kids],
+            "hlc_ms": self.hlc_ms,
+            "revision_id": self.revision_id,
+        }
+
+
+class BeliefRevisionError(ValueError):
+    """Raised when a revision request is malformed (e.g. no evidence)."""
+
+
+# ---------------------------------------------------------------------------
+# BeliefStore
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _BeliefHistoryEntry:
+    record: BeliefRecord
+    superseded_by: str | None = None  # revision_id that replaced this one
+
+
+class BeliefStore:
+    """Per-(subject, topic) belief index with AGM revision semantics.
+
+    Indexed by ``(subject_kid, topic, proposition_hash)``. A *revision*
+    over (ϕ, evidence) walks the AGM postulates:
+
+      1. Success: the resulting store contains a record asserting ϕ.
+      2. Inclusion: only the (ϕ, ¬ϕ) pair is touched; other propositions
+         on the same topic are left intact.
+      3. Vacuity: if ¬ϕ is not currently held, the revision degenerates
+         to expansion — the new record is appended without contraction.
+      4. Extensionality: if proposition bytes are equal (modulo CBOR-
+         canonical encoding), revision IDs round-trip equal beliefs.
+
+    Contradiction handling: if ¬ϕ is currently held with posterior_mean
+    > 0.5 AND the new evidence raises ϕ's posterior_mean > 0.5, the
+    contradiction is recorded in :attr:`fork_log` (deque, bounded at 100)
+    and *both* records remain queryable until an oracle resolves which
+    branch survives.
+    """
+
+    def __init__(self) -> None:
+        # (subject_kid, topic, prop_hash) -> current BeliefRecord
+        self._beliefs: dict[tuple[bytes, str, bytes], BeliefRecord] = {}
+        # All historical revisions ordered by HLC for snapshot().
+        self._history: list[_BeliefHistoryEntry] = []
+        self.fork_log: deque[dict[str, Any]] = deque(maxlen=100)
+
+    # ---- queries ----------------------------------------------------------
+
+    def get(
+        self,
+        subject_kid: bytes,
+        topic: str,
+        proposition: bytes,
+    ) -> BeliefRecord | None:
+        key = (bytes(subject_kid), topic, proposition_hash(proposition))
+        return self._beliefs.get(key)
+
+    def all_for(self, subject_kid: bytes, topic: str | None = None) -> list[BeliefRecord]:
+        out: list[BeliefRecord] = []
+        for (kid, tpc, _), rec in self._beliefs.items():
+            if kid != bytes(subject_kid):
+                continue
+            if topic is not None and tpc != topic:
+                continue
+            out.append(rec)
+        return out
+
+    def history(self) -> list[BeliefRecord]:
+        return [h.record for h in self._history]
+
+    # ---- mutators ---------------------------------------------------------
+
+    def expand(self, belief: BeliefRecord) -> BeliefRecord:
+        """AGM expansion — add ϕ when ¬ϕ is not currently held.
+
+        Idempotent: re-adding a logically-equal proposition replaces the
+        record in place (extensionality). Returns the stored record.
+        """
+        if not belief.evidence_kids:
+            raise BeliefRevisionError(
+                "BeliefRecord MUST cite at least one evidence_kid; see spec §21 normative MUST."
+            )
+        key = (bytes(belief.subject_kid), belief.topic, belief.proposition_hash)
+        self._beliefs[key] = belief
+        self._history.append(_BeliefHistoryEntry(record=belief))
+        return belief
+
+    def contract(
+        self,
+        subject_kid: bytes,
+        topic: str,
+        proposition: bytes,
+    ) -> BeliefRecord | None:
+        """AGM contraction — drop ϕ from the belief set if held.
+
+        Returns the contracted record (now removed) or None if no such
+        belief existed. The history retains the contraction event.
+        """
+        key = (bytes(subject_kid), topic, proposition_hash(proposition))
+        existing = self._beliefs.pop(key, None)
+        if existing is not None:
+            self._history.append(
+                _BeliefHistoryEntry(
+                    record=existing,
+                    superseded_by="contracted",
+                )
+            )
+        return existing
+
+    def revise(self, belief: BeliefRecord, new_evidence: tuple[bytes, ...] = ()) -> BeliefRecord:
+        """AGM revision: contract ¬ϕ if present, then expand ϕ.
+
+        ``new_evidence`` is appended to ``belief.evidence_kids`` before
+        storing — the caller may pass the bare BeliefRecord and let the
+        store accumulate evidence kids across revisions.
+        """
+        # Build the merged evidence tuple.
+        merged_ev = tuple(belief.evidence_kids) + tuple(bytes(e) for e in new_evidence)
+        if not merged_ev:
+            raise BeliefRevisionError(
+                "revise() requires at least one evidence_kid (spec §21 MUST)."
+            )
+        merged = BeliefRecord(
+            subject_kid=belief.subject_kid,
+            topic=belief.topic,
+            proposition=belief.proposition,
+            alpha=belief.alpha,
+            beta=belief.beta,
+            evidence_kids=merged_ev,
+            hlc_ms=belief.hlc_ms or int(time.time() * 1000),
+            revision_id=belief.revision_id,
+        )
+
+        # Look for ¬ϕ — encoded as the "negation" of the proposition.
+        # We treat negation as a CBOR-canonical wrapper {"_not": proposition}.
+        not_prop = cbor2.dumps({"_not": belief.proposition}, canonical=True)
+        not_key = (
+            bytes(belief.subject_kid),
+            belief.topic,
+            proposition_hash(not_prop),
+        )
+        existing_neg = self._beliefs.get(not_key)
+        if existing_neg is not None and existing_neg.posterior_mean > 0.5:
+            # Contradiction: ¬ϕ currently held with majority belief.
+            if merged.posterior_mean > 0.5:
+                self.fork_log.append(
+                    {
+                        "store": "belief",
+                        "subject_kid": bytes(belief.subject_kid).hex(),
+                        "topic": belief.topic,
+                        "hlc_ms": merged.hlc_ms,
+                        "phi_revision": merged.revision_id,
+                        "not_phi_revision": existing_neg.revision_id,
+                        "reason": "AGM-CONTRADICTION-FORK",
+                    }
+                )
+                _log.warning(
+                    "BeliefStore fork: subject=%s topic=%s — both ϕ and ¬ϕ believed",
+                    bytes(belief.subject_kid)[:4].hex(),
+                    belief.topic,
+                )
+                # Both records survive; an oracle resolution will retire one.
+                return self.expand(merged)
+            # Otherwise: contract ϕ instead — ¬ϕ stronger; vacuity holds.
+            self.contract(belief.subject_kid, belief.topic, belief.proposition)
+            return existing_neg
+
+        # No conflicting ¬ϕ — vacuity: revision == expansion.
+        return self.expand(merged)
+
+    # ---- snapshot ---------------------------------------------------------
+
+    def snapshot(self, *, at_hlc_ms: int) -> list[BeliefRecord]:
+        """Return the set of beliefs that were current at ``at_hlc_ms``.
+
+        A record R is "current at H" iff R.hlc_ms ≤ H AND no later
+        record (with the same key) supersedes R by H. Contracted records
+        appear as removed.
+        """
+        # Walk history in HLC order; rebuild the live set up to at_hlc_ms.
+        live: dict[tuple[bytes, str, bytes], BeliefRecord] = {}
+        ordered = sorted(self._history, key=lambda h: h.record.hlc_ms)
+        for entry in ordered:
+            if entry.record.hlc_ms > at_hlc_ms:
+                break
+            key = (
+                bytes(entry.record.subject_kid),
+                entry.record.topic,
+                entry.record.proposition_hash,
+            )
+            if entry.superseded_by == "contracted":
+                live.pop(key, None)
+            else:
+                live[key] = entry.record
+        return list(live.values())
+
+
+# ---------------------------------------------------------------------------
+# Theory of Mind
+# ---------------------------------------------------------------------------
+
+
+class TheoryOfMind:
+    """Per-(self_agent, peer_kid) snapshot of *what self thinks peer believes*.
+
+    Internally holds one :class:`BeliefStore` keyed by ``peer_kid`` so a
+    single ToM tracker handles many peers. Updated by observations of
+    peer-signed claims; consumed by Deliberator scoring.
+    """
+
+    def __init__(self, self_kid: bytes) -> None:
+        self.self_kid = bytes(self_kid)
+        self._stores: dict[bytes, BeliefStore] = {}
+
+    def store_for(self, peer_kid: bytes) -> BeliefStore:
+        peer = bytes(peer_kid)
+        if peer not in self._stores:
+            self._stores[peer] = BeliefStore()
+        return self._stores[peer]
+
+    def update_from_observation(
+        self,
+        peer_kid: bytes,
+        *,
+        topic: str,
+        proposition: bytes,
+        evidence_kid: bytes,
+        posterior_mean: float,
+        hlc_ms: int | None = None,
+        n_pseudo_obs: float = 4.0,
+    ) -> BeliefRecord:
+        """Update peer model from a single observed claim.
+
+        ``posterior_mean`` is the peer's stated posterior on ϕ; we map
+        it onto a Beta(α, β) with effective sample size ``n_pseudo_obs``.
+        """
+        if not (0.0 <= posterior_mean <= 1.0):
+            raise BeliefRevisionError(f"posterior_mean must be in [0,1]; got {posterior_mean!r}")
+        alpha = 1.0 + n_pseudo_obs * posterior_mean
+        beta = 1.0 + n_pseudo_obs * (1.0 - posterior_mean)
+        rec = BeliefRecord(
+            subject_kid=bytes(peer_kid),
+            topic=topic,
+            proposition=bytes(proposition),
+            alpha=alpha,
+            beta=beta,
+            evidence_kids=(bytes(evidence_kid),),
+            hlc_ms=hlc_ms if hlc_ms is not None else int(time.time() * 1000),
+        )
+        return self.store_for(peer_kid).revise(rec)
+
+    def belief(
+        self,
+        peer_kid: bytes,
+        topic: str,
+        proposition: bytes,
+    ) -> BeliefRecord | None:
+        return self.store_for(peer_kid).get(peer_kid, topic, proposition)
+
+    def posterior_mean(
+        self,
+        peer_kid: bytes,
+        topic: str,
+        proposition: bytes,
+        *,
+        default: float = 0.5,
+    ) -> float:
+        rec = self.belief(peer_kid, topic, proposition)
+        return rec.posterior_mean if rec is not None else default
+
+    def peers(self) -> list[bytes]:
+        return list(self._stores.keys())