hypermind 0.11.0__py3-none-any.whl

hypermind/mind/diversity.py

@@ -0,0 +1,144 @@
+"""DiversityGuard — block correlated synthesis.
+
+Failure mode (design/failure-modes.md:13): if all panel members cite
+the same upstream sources, their posteriors are not independent and
+the synthesis aggregates the *same* signal multiple times — Condorcet
+breakdown. Reputation does nothing about this.
+
+The guard takes panel members' citation graphs (parent_kids per
+member's most-recent claim on the topic) and computes pairwise
+Jaccard overlap. If the mean overlap exceeds ``threshold``, the guard
+flags ``epistemic_dependence`` in the synthesis payload — the caller
+chooses whether to abort, downweight, or simply log.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class EpistemicDependence:
+    mean_jaccard: float
+    threshold: float
+    flagged: bool
+    pairs: int
+
+    def as_dict(self) -> dict[str, float | bool | int]:
+        return {
+            "mean_jaccard": self.mean_jaccard,
+            "threshold": self.threshold,
+            "flagged": self.flagged,
+            "pairs": self.pairs,
+        }
+
+
+@dataclass(frozen=True)
+class QuorumResult:
+    """T4-05 first-class quorum verdict."""
+
+    passed: bool
+    independent_count: int
+    required: int
+    mean_jaccard: float
+
+    def as_dict(self) -> dict[str, float | bool | int]:
+        return {
+            "passed": self.passed,
+            "independent_count": self.independent_count,
+            "required": self.required,
+            "mean_jaccard": self.mean_jaccard,
+        }
+
+
+@dataclass
+class DiversityGuard:
+    threshold: float = 0.6
+    #: T4-05 — minimum number of pairwise-independent members required
+    #: for ``check_quorum`` to pass. Pairs with Jaccard ≥ ``threshold``
+    #: are treated as dependent.
+    quorum_k: int = 2
+
+    def check_quorum(
+        self,
+        panel: Sequence[Any],
+    ) -> QuorumResult:
+        """Return True iff ≥ ``quorum_k`` panel members are sufficiently
+        independent on cited evidence.
+
+        Accepts panel members that expose either a ``citations`` /
+        ``parent_kids`` attribute or are themselves a sequence of bytes.
+        """
+        citations: list[list[bytes]] = []
+        for m in panel:
+            cs = (
+                getattr(m, "citations", None)
+                or getattr(m, "parent_kids", None)
+                or (m if isinstance(m, (list, tuple, set)) else None)
+            )
+            citations.append([bytes(c) for c in (cs or [])])
+        # Build an independence graph: members are independent if their
+        # pairwise Jaccard < threshold.
+        indep_set: list[int] = []
+        sets = [set(cs) for cs in citations]
+        for i, s_i in enumerate(sets):
+            ok = True
+            for j in indep_set:
+                s_j = sets[j]
+                union = s_i | s_j
+                jacc = len(s_i & s_j) / len(union) if union else 0.0
+                if jacc >= self.threshold:
+                    ok = False
+                    break
+            if ok:
+                indep_set.append(i)
+        # Compute mean overlap for diagnostics.
+        total = 0.0
+        n = 0
+        non_empty = [s for s in sets if s]
+        for i in range(len(non_empty)):
+            for j in range(i + 1, len(non_empty)):
+                a, b = non_empty[i], non_empty[j]
+                union = a | b
+                if not union:
+                    continue
+                total += len(a & b) / len(union)
+                n += 1
+        mean = total / n if n else 0.0
+        return QuorumResult(
+            passed=len(indep_set) >= self.quorum_k,
+            independent_count=len(indep_set),
+            required=self.quorum_k,
+            mean_jaccard=mean,
+        )
+
+    def assess(
+        self,
+        member_citations: Sequence[Sequence[bytes]],
+    ) -> EpistemicDependence:
+        sets = [set(bytes(p) for p in cs) for cs in member_citations]
+        # Drop members with no citations — they contribute no overlap signal.
+        sets = [s for s in sets if s]
+        if len(sets) < 2:
+            return EpistemicDependence(
+                mean_jaccard=0.0, threshold=self.threshold, flagged=False, pairs=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
+        mean = total / n if n else 0.0
+        return EpistemicDependence(
+            mean_jaccard=mean,
+            threshold=self.threshold,
+            flagged=mean >= self.threshold,
+            pairs=n,
+        )

hypermind/mind/evolve.py

@@ -0,0 +1,184 @@
+"""SelfReflector — evolve from your own track record.
+
+Reads the agent's own per-topic Beta posterior trajectory and adjusts
+bound policy thresholds. Closes the loop the spec already named
+"evolve" but never wired: outcomes → policy updates → better future
+actions.
+
+Three components:
+    SelfReflector  — periodic introspection that ratchets policy thresholds
+    BrierFeedback  — pulls v0.6 Brier shrinkage into working_memory posteriors
+    MentorFollowing — weights consult results from better-calibrated peers higher
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from typing import Any
+
+from hypermind.knowledge.reputation import ReputationKernel
+from hypermind.mind.policy import (
+    ActionPolicy,
+    CheckpointOnSignalGain,
+    ConsultOnDisagreement,
+    DisputeOnContradiction,
+    LeverageCap,
+    PublishWhenConfident,
+)
+
+
+@dataclass
+class SelfReflector:
+    """Adjust policy thresholds based on the agent's own outcome history.
+
+    Heuristic:
+      * Falling momentum_z (z < -0.5) AND recent publishes  → tighten
+        PublishWhenConfident (raise threshold by +0.05 up to 0.97).
+      * Stable, high momentum (z > +0.5)                    → relax
+        PublishWhenConfident (lower threshold by -0.02 down to 0.6).
+      * Brier > 0.25                                         → tighten
+        DisputeOnContradiction (raise min_rep_delta by +0.05).
+
+    Idempotent — calling reflect() twice in a row without new outcomes
+    is a no-op. Operates in-place on the policy objects.
+    """
+
+    agent_kid: bytes
+    topic: str
+    reputation: ReputationKernel
+    publish_floor: float = 0.6
+    publish_ceiling: float = 0.97
+    publish_step: float = 0.05
+    dispute_step: float = 0.05
+    history: list[dict[str, Any]] = field(default_factory=list)
+
+    def reflect(self, policies: Iterable[ActionPolicy]) -> dict[str, Any]:
+        snap = self.reputation.snapshot(self.agent_kid, self.topic)
+        # Brier may not be wired in this kernel until first oracle resolves.
+        brier_adj = self.reputation.calibration_adjustment(self.agent_kid, self.topic)
+        # adjustment ∈ [0.5, 2.0]; values < 1 mean "this agent is overconfident".
+        is_overconfident = brier_adj < 1.0
+        is_underconfident = brier_adj > 1.0
+
+        action_log: dict[str, Any] = {
+            "score": snap.score,
+            "z": snap.momentum_z,
+            "n": snap.n_observations,
+            "brier_adj": brier_adj,
+            "changes": [],
+        }
+
+        for pol in policies:
+            inner = pol.inner if isinstance(pol, LeverageCap) else pol
+            if isinstance(inner, PublishWhenConfident):
+                old = inner.threshold
+                if is_overconfident or snap.momentum_z < -0.5:
+                    new = min(self.publish_ceiling, old + self.publish_step)
+                elif is_underconfident and snap.momentum_z > 0.5:
+                    new = max(self.publish_floor, old - (self.publish_step / 2.0))
+                else:
+                    new = old
+                if new != old:
+                    inner.threshold = new
+                    action_log["changes"].append(
+                        {"policy": "PublishWhenConfident", "threshold": [old, new]}
+                    )
+            elif isinstance(inner, DisputeOnContradiction):
+                old = inner.min_rep_delta
+                if is_overconfident:
+                    new = min(0.5, old + self.dispute_step)
+                else:
+                    new = old
+                if new != old:
+                    inner.min_rep_delta = new
+                    action_log["changes"].append(
+                        {"policy": "DisputeOnContradiction", "min_rep_delta": [old, new]}
+                    )
+            elif isinstance(inner, ConsultOnDisagreement):
+                # If we're often wrong, consult sooner (lower divergence threshold).
+                old = inner.divergence
+                if is_overconfident:
+                    new = max(0.1, old - 0.05)
+                else:
+                    new = old
+                if new != old:
+                    inner.divergence = new
+                    action_log["changes"].append(
+                        {"policy": "ConsultOnDisagreement", "divergence": [old, new]}
+                    )
+            elif isinstance(inner, CheckpointOnSignalGain):
+                # No change here — KL threshold isn't outcome-driven.
+                pass
+        self.history.append(action_log)
+        return action_log
+
+
+@dataclass
+class BrierFeedback:
+    """Apply Brier shrinkage directly to working_memory posteriors.
+
+    An overconfident agent's working_memory[topic] posterior is pulled
+    toward 0.5 by the calibration_adjustment factor — so the *next*
+    publish is automatically more humble.
+
+    S4 — When ``persona`` is set, the post-shrinkage value is also
+    written through to the KernelStore on disk so the next sim that
+    instantiates this persona starts with a calibrated prior. Optional;
+    persona="" keeps the legacy in-process-only behaviour.
+    """
+
+    agent_kid: bytes
+    reputation: ReputationKernel
+    persona: str = ""
+
+    def apply(self, working_memory: dict[str, Any], topic: str) -> float | None:
+        posteriors = working_memory.setdefault("posteriors", {})
+        score = posteriors.get(topic)
+        if score is None:
+            return None
+        adj = self.reputation.calibration_adjustment(self.agent_kid, topic)
+        if adj >= 1.0:
+            return score  # well-calibrated or no signal yet → leave alone
+        # Pull toward 0.5 by (1 - adj) — adj=0.5 ⇒ shrink halfway.
+        shrink = 1.0 - adj
+        new = score + (0.5 - score) * shrink
+        posteriors[topic] = new
+        # S4 — best-effort persistence to KernelStore. Never raise back
+        # to the agent; calibration improvement is operational, not load-
+        # bearing for any spec invariant.
+        if self.persona:
+            try:
+                from hypermind.knowledge.kernel_store import KernelStore
+
+                KernelStore.update(self.persona, topic, posterior=new)
+            except Exception:
+                pass
+        return new
+
+
+@dataclass
+class MentorFollowing:
+    """Weight consult results by mentor calibration quality.
+
+    Given (peer_kid → posterior) returned from a panel, returns a
+    re-weighted aggregate where each peer's vote is multiplied by their
+    Brier-derived calibration adjustment (≥1 = better than us, <1 =
+    worse). Normalises so weights sum to 1.
+    """
+
+    reputation: ReputationKernel
+
+    def reweight(
+        self,
+        topic: str,
+        votes: dict[bytes, float],
+    ) -> tuple[dict[bytes, float], float]:
+        weights: dict[bytes, float] = {}
+        for kid in votes:
+            adj = self.reputation.calibration_adjustment(bytes(kid), topic)
+            weights[bytes(kid)] = max(0.05, adj)
+        total = sum(weights.values()) or 1.0
+        norm = {k: w / total for k, w in weights.items()}
+        weighted = sum(votes[k] * norm[bytes(k)] for k in votes)
+        return norm, weighted

hypermind/mind/federation.py

@@ -0,0 +1,154 @@
+"""Autonomous federation — bridges that decide when to relay.
+
+Wraps the existing cross-namespace consult pattern (see
+examples/scenario_cross_namespace_federation.py) with a deliberation
+trigger: the bridge agent's deliberator initiates a foreign-namespace
+consult ONLY when the home namespace is uncertain AND the foreign
+namespace has enough qualified agents.
+
+Foreign reputation is never merged into the home kernel — it is
+displayed in the synthesis payload, mirroring the existing v0.4
+invariant. We add a strict ``never_merge`` assertion as a guard rail.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from hypermind.agent import HyperMindAgent
+
+
+@dataclass
+class FederationPolicy:
+    """Decision rule for when to relay a query across namespaces."""
+
+    home_uncertainty_threshold: float = 0.3
+    """Trigger when the home consult has stdev >= threshold."""
+
+    min_foreign_qualified: int = 2
+    """Need at least this many foreign agents above the rep floor."""
+
+    foreign_rep_floor: float = 0.55
+    """Foreign agents must be at least this reputable on the topic."""
+
+    def should_relay(
+        self,
+        *,
+        home_disagreement: float,
+        foreign_qualified: int,
+    ) -> bool:
+        return (
+            home_disagreement >= self.home_uncertainty_threshold
+            and foreign_qualified >= self.min_foreign_qualified
+        )
+
+
+def assert_never_merge(home_state: dict[str, Any], foreign_payload: dict[str, Any]) -> None:
+    """Guard: foreign reputation must NEVER appear inside home kernel keys.
+
+    Raises ValueError if a foreign reputation map has bled into the
+    home agent's local kernel snapshot. Used by federation tests.
+    """
+    home_kids = set(home_state.get("home_reputation", {}).keys())
+    foreign_kids = set(foreign_payload.get("foreign_reputation", {}).keys())
+    leaked = home_kids & foreign_kids
+    if leaked:
+        raise ValueError(
+            f"FEDERATION-NEVER-MERGE violation: foreign kids {sorted(leaked)} "
+            f"appear in home reputation map. Foreign reputation must remain "
+            f"displayed-only (per scenario_cross_namespace_federation invariant)."
+        )
+
+
+async def auto_relay(
+    bridge: HyperMindAgent,
+    *,
+    topic: str,
+    foreign_namespace_id: bytes,
+    foreign_candidate_kids: Iterable[bytes],
+    policy: FederationPolicy | None = None,
+    caller_disagreement_hint: float | None = None,
+) -> dict[str, Any] | None:
+    """Run the deliberator-style federation check; relay if the policy fires.
+
+    The caller may pass ``caller_disagreement_hint`` to suggest an
+    expected home-namespace disagreement value, but it is treated as a
+    HINT only — never as authoritative input. The bridge always
+    measures the actual disagreement from its own home-namespace state
+    (reputation-snapshot stdev across home agents on the topic) and
+    clamps the caller's hint so it can only LOWER the value, never
+    inflate it. This closes a vulnerability where a caller could pass
+    ``home_disagreement=999`` to bypass the policy gate.
+
+    Returns the synthesis payload (foreign rep displayed-only) or None
+    if the policy declined to relay. The bridge's *own* consult and
+    synthesize verbs are used — no bypass of the agent API.
+    """
+    policy = policy or FederationPolicy()
+    world = getattr(bridge, "_world", None)
+    if world is None:
+        return None
+
+    # Measure home-namespace disagreement from the bridge's own state:
+    # stdev of reputation snapshots across home agents on the topic.
+    home_world = world
+    measured_disagreement = 0.0
+    scores = [
+        home_world.reputation.snapshot(kid, topic).score
+        for kid in home_world.agents.keys()
+        if kid != bridge.keypair.kid and topic in home_world.agents[kid].rooms
+    ]
+    if len(scores) >= 2:
+        mean = sum(scores) / len(scores)
+        var = sum((s - mean) ** 2 for s in scores) / len(scores)
+        import math
+
+        measured_disagreement = math.sqrt(var)
+
+    # Caller's hint can only LOWER the measured value, never inflate it.
+    if caller_disagreement_hint is not None:
+        home_disagreement = min(caller_disagreement_hint, measured_disagreement)
+    else:
+        home_disagreement = measured_disagreement
+
+    qualified = 0
+    foreign_rep: dict[bytes, float] = {}
+    # Look up the foreign namespace's reputation kernel via the registry.
+    from hypermind.agent import _lookup_namespace  # local import to avoid cycle
+
+    foreign_world = _lookup_namespace(bytes(foreign_namespace_id))
+    if foreign_world is None:
+        return None
+    for kid in foreign_candidate_kids:
+        snap = foreign_world.reputation.snapshot(bytes(kid), topic)
+        foreign_rep[bytes(kid)] = snap.score
+        if snap.score >= policy.foreign_rep_floor:
+            qualified += 1
+
+    if not policy.should_relay(
+        home_disagreement=home_disagreement,
+        foreign_qualified=qualified,
+    ):
+        return None
+
+    # Best-effort cross-namespace consult.
+    try:
+        result = await bridge.consult(
+            query=f"federation:{topic}",
+            topic=topic,
+            panel_size=min(3, qualified),
+            cross_namespace=[bytes(foreign_namespace_id)],
+        )
+    except Exception:
+        return None
+    return {
+        "topic": topic,
+        "foreign_namespace_id": bytes(foreign_namespace_id).hex(),
+        "foreign_reputation": {k.hex(): v for k, v in foreign_rep.items()},
+        "aggregated_posterior": float(result.posterior.mean()),
+        "panel_size": len(result.panel),
+        "rule": "FEDERATION-AUTO-RELAY",
+    }

hypermind/mind/goals.py

@@ -0,0 +1,117 @@
+"""Goals — what an autonomous agent is trying to achieve.
+
+A Goal is a declarative target: a topic, a confidence threshold, an
+optional deadline, and an optional success predicate. The Deliberator
+walks active goals each tick and picks an action per the bound policies.
+
+Goals are immutable. State (ACTIVE / SATISFIED / EXPIRED / ABANDONED)
+lives on a paired GoalStatus row in the queue.
+"""
+
+from __future__ import annotations
+
+import time
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+
+class GoalOutcome(StrEnum):
+    ACTIVE = "active"
+    SATISFIED = "satisfied"
+    EXPIRED = "expired"
+    ABANDONED = "abandoned"
+
+
+@dataclass(frozen=True)
+class Goal:
+    """A declarative target an agent will autonomously pursue."""
+
+    topic: str
+    target_confidence: float = 0.8
+    deadline_ms: int | None = None  # wall-clock ms; None = no deadline
+    success_predicate: Callable[[dict[str, Any]], bool] | None = None
+    description: str = ""
+    goal_id: str = field(default_factory=lambda: uuid.uuid4().hex)
+    created_ms: int = field(default_factory=lambda: int(time.time() * 1000))
+
+    def __post_init__(self) -> None:
+        if not 0.0 < self.target_confidence <= 1.0:
+            raise ValueError(f"target_confidence must be in (0, 1]; got {self.target_confidence}")
+        if not self.topic:
+            raise ValueError("topic must be a non-empty string")
+
+    def is_expired(self, *, now_ms: int | None = None) -> bool:
+        if self.deadline_ms is None:
+            return False
+        return (now_ms if now_ms is not None else int(time.time() * 1000)) >= self.deadline_ms
+
+    def is_satisfied(self, working_memory: dict[str, Any]) -> bool:
+        """Default satisfaction: posterior_for(topic) >= target_confidence.
+
+        A custom success_predicate overrides this entirely.
+        """
+        if self.success_predicate is not None:
+            return bool(self.success_predicate(working_memory))
+        posteriors = working_memory.get("posteriors", {})
+        score = posteriors.get(self.topic)
+        return score is not None and score >= self.target_confidence
+
+
+@dataclass
+class GoalStatus:
+    goal: Goal
+    outcome: GoalOutcome = GoalOutcome.ACTIVE
+    last_action: str | None = None
+    last_action_ms: int | None = None
+    actions_taken: int = 0
+    notes: list[str] = field(default_factory=list)
+
+
+class GoalQueue:
+    """In-memory queue of goals an agent is pursuing.
+
+    Not thread-safe; the Deliberator owns it within a single asyncio task.
+    """
+
+    def __init__(self) -> None:
+        self._statuses: dict[str, GoalStatus] = {}
+
+    def add(self, goal: Goal) -> GoalStatus:
+        if goal.goal_id in self._statuses:
+            return self._statuses[goal.goal_id]
+        status = GoalStatus(goal=goal)
+        self._statuses[goal.goal_id] = status
+        return status
+
+    def remove(self, goal_id: str) -> None:
+        self._statuses.pop(goal_id, None)
+
+    def active(self) -> list[GoalStatus]:
+        return [s for s in self._statuses.values() if s.outcome is GoalOutcome.ACTIVE]
+
+    def all(self) -> list[GoalStatus]:
+        return list(self._statuses.values())
+
+    def get(self, goal_id: str) -> GoalStatus | None:
+        return self._statuses.get(goal_id)
+
+    def reap(self, working_memory: dict[str, Any], *, now_ms: int | None = None) -> int:
+        """Mark satisfied/expired goals; return the count reaped."""
+        reaped = 0
+        for status in self._statuses.values():
+            if status.outcome is not GoalOutcome.ACTIVE:
+                continue
+            if status.goal.is_satisfied(working_memory):
+                status.outcome = GoalOutcome.SATISFIED
+                reaped += 1
+                continue
+            if status.goal.is_expired(now_ms=now_ms):
+                status.outcome = GoalOutcome.EXPIRED
+                reaped += 1
+        return reaped
+
+    def __len__(self) -> int:
+        return len(self._statuses)