hypermind 0.14.0__tar.gz → 0.15.0__tar.gz

{hypermind-0.14.0 → hypermind-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypermind
-Version: 0.14.0
+Version: 0.15.0
 Summary: Federated agent intelligence — reference SDK for the HyperMind SCITT contested-claims profile
 Project-URL: Homepage, https://github.com/ZySec-AI/hypermind
 Project-URL: Documentation, https://github.com/ZySec-AI/hypermind/tree/main/docs

{hypermind-0.14.0 → hypermind-0.15.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypermind"
-version = "0.14.0"
+version = "0.15.0"
 description = "Federated agent intelligence — reference SDK for the HyperMind SCITT contested-claims profile"
 readme = "README.md"
 requires-python = ">=3.11,<3.14"

{hypermind-0.14.0 → hypermind-0.15.0}/src/hypermind/__init__.py

@@ -73,7 +73,7 @@ open = HyperMindAgent.open
 #: is held until the §External & human gates clear (IETF I-D, IANA,
 #: third-party audit, OpenSSF acceptance, ≥3 pilots) — at that point we
 #: cut ``1.0.0`` GA. See ROADMAP.md §Status snapshot.
-__version__ = "0.14.0"
+__version__ = "0.15.0"
 
 #: SLSA build-provenance level committed for every release artefact.
 #: Cosign keyless signing + slsa-github-generator + PEP 740 attestations

{hypermind-0.14.0 → hypermind-0.15.0}/src/hypermind/orgs/__init__.py

@@ -24,6 +24,8 @@ worked examples of the mapping.
 
 from __future__ import annotations
 
+from hypermind.orgs.context import ContextBuilder, default_context_builder
+from hypermind.orgs.deliberate import build_deliberator, policies_for_role
 from hypermind.orgs.experiment import (
     Experiment,
     ExperimentResult,
@@ -57,8 +59,10 @@ from hypermind.orgs.model import (
     Slot,
     Unit,
 )
+from hypermind.orgs.receipt import VerifyResult, build_receipt, verify_receipt
 from hypermind.orgs.report import MemberStanding, OrgReport
 from hypermind.orgs.sim import OrgSim
+from hypermind.orgs.stream import graph_snapshot
 from hypermind.orgs.tools import (
     build_tool,
     declarative_grants,
@@ -71,6 +75,7 @@ from hypermind.orgs.tools import (
 __all__ = [
     "Adversarial",
     "CallableGroundTruth",
+    "ContextBuilder",
     "Cooperative",
     "Crowd",
     "DynamicsConfig",
@@ -94,12 +99,19 @@ __all__ = [
     "Unit",
     "Variant",
     "VariantResult",
+    "VerifyResult",
+    "build_deliberator",
+    "build_receipt",
     "build_tool",
     "compute_scorecard",
     "declarative_grants",
+    "default_context_builder",
     "get_interaction",
+    "graph_snapshot",
     "list_tools",
+    "policies_for_role",
     "random_grants",
     "register_tool",
     "unregister_tool",
+    "verify_receipt",
 ]

hypermind-0.15.0/src/hypermind/orgs/context.py

@@ -0,0 +1,35 @@
+"""Memory-grounded reasoning context (#153).
+
+Before a member reasons, it retrieves what it concluded before (its private
+Relata notebook) and what peers have claimed on the topic (the shared ledger),
+and assembles a *structured* prompt block instead of a flat string join. This
+turns "learn across rounds" from cosmetic into real: prior findings and peer
+positions actually shape the next answer.
+
+The builder is injectable — pass ``context_builder=`` to ``OrgSim`` to change
+the prompt shape without touching the engine.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+
+class ContextBuilder(Protocol):
+    def __call__(self, *, topic: str, own_notes: list[str], peer_findings: list[str]) -> str: ...
+
+
+def default_context_builder(*, topic: str, own_notes: list[str], peer_findings: list[str]) -> str:
+    """Assemble a structured reasoning prompt from retrieved context."""
+    parts = [topic]
+    if own_notes:
+        parts.append(
+            "What you concluded in earlier rounds:\n" + "\n".join(f"- {n}" for n in own_notes)
+        )
+    if peer_findings:
+        parts.append(
+            "What peers have claimed on this topic:\n" + "\n".join(f"- {p}" for p in peer_findings)
+        )
+    if own_notes or peer_findings:
+        parts.append("Weigh this prior context, then give your current calibrated answer.")
+    return "\n\n".join(parts)

hypermind-0.15.0/src/hypermind/orgs/deliberate.py

@@ -0,0 +1,44 @@
+"""Deliberator mode (#154) — drive the loop with the real mind-layer.
+
+Opt-in via ``DynamicsConfig(mode="deliberator")``. Instead of the scripted
+phases, each member gets a real :class:`~hypermind.mind.deliberator.Deliberator`
+bound with its **role's** policy bundle (from ``hypermind.mind.roles``). Each
+round the member observes its peers' posteriors and ``tick()``s — publish /
+consult / dispute / checkpoint decisions come from the policies, dispatched
+through the agent's own verbs (the Deliberator logs any capability-gated skips
+rather than raising). The per-tick decisions are recorded as a trace on the
+report.
+
+This reuses the sophisticated machinery that the scripted engine deliberately
+keeps simple, without duplicating its logic.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def policies_for_role(role: str, *, topic: str = "*") -> list[Any]:
+    """The mind-layer ``ActionPolicy`` bundle for a seat role.
+
+    Falls back to the generalist bundle for any role the mind layer doesn't
+    define policies for.
+    """
+    from hypermind.mind.roles import generalist, role_by_name
+
+    try:
+        return list(role_by_name(role, topic=topic).policies)
+    except (ValueError, KeyError):
+        return list(generalist(topic=topic).policies)
+
+
+def build_deliberator(agent: Any, *, role: str, topic: str) -> Any:
+    """Construct a Deliberator for an agent, pursuing a goal on ``topic``."""
+    from hypermind.mind.deliberator import Deliberator
+    from hypermind.mind.goals import Goal
+
+    delib = Deliberator(
+        agent, policies=policies_for_role(role, topic=topic), broadcast_mind_records=False
+    )
+    delib.pursue(Goal(topic=topic, target_confidence=0.8))
+    return delib

{hypermind-0.14.0 → hypermind-0.15.0}/src/hypermind/orgs/interaction.py

@@ -69,7 +69,13 @@ class Interaction:
 
     # ---- dispute -------------------------------------------------------
     def should_dispute(
-        self, *, disputer_role: str, disputer_mean: float, claim: ClaimRec, gap: float
+        self,
+        *,
+        disputer_role: str,
+        disputer_unit: str,
+        disputer_mean: float,
+        claim: ClaimRec,
+        gap: float,
     ) -> bool:
         """Whether ``disputer`` challenges ``claim``. Cooperative: only
         sceptics, only on a wide belief gap."""
@@ -85,16 +91,43 @@ class Interaction:
             return ground_truth
         return claim.confidence >= 0.5
 
+    # ---- state ---------------------------------------------------------
+    def state(self) -> dict[str, object]:
+        """Extra strategy state to expose on the report (e.g. power balance)."""
+        return {}
+
 
 class Cooperative(Interaction):
     name = "cooperative"
 
 
 class Adversarial(Interaction):
-    """Rival units: cite your own side, attack the other side."""
+    """Rival coalitions with a shifting power balance.
+
+    Units are grouped into **coalitions** (default: each unit its own). Members
+    rally their coalition (cite allies) and attack rivals (dispute out-of-
+    coalition claims). A per-unit **power** score rises when a unit's claims
+    resolve correctly and falls when they don't; strong factions **escalate**
+    (dispute more readily), weak ones **concede** (dispute less) — so the fight
+    is dynamic instead of collapsing to all-dispute-no-publish.
+    """
 
     name = "adversarial"
 
+    def __init__(
+        self, *, coalitions: dict[str, str] | None = None, escalation: float = 0.25
+    ) -> None:
+        self._coalitions = dict(coalitions or {})
+        self._escalation = escalation
+        self._power: dict[str, float] = {}
+        self._timeline: list[dict[str, object]] = []
+
+    def _coalition(self, unit: str) -> str:
+        return self._coalitions.get(unit, unit)
+
+    def _allied(self, unit_a: str, unit_b: str) -> bool:
+        return self._coalition(unit_a) == self._coalition(unit_b)
+
     def cite_targets(
         self,
         *,
@@ -103,23 +136,45 @@ class Adversarial(Interaction):
         own_kid: bytes,
         claims: list[ClaimRec],
     ) -> list[bytes]:
-        # Cite the strongest claim from *your own* unit (rally your side).
-        allies = [c for c in claims if c.unit == member_unit and c.kid != own_kid]
+        # Rally your coalition: cite the strongest allied claim.
+        allies = [c for c in claims if c.kid != own_kid and self._allied(c.unit, member_unit)]
         if not allies:
             return []
-        best = max(allies, key=lambda c: c.confidence)
-        return [best.kid]
+        return [max(allies, key=lambda c: c.confidence).kid]
 
     def should_dispute(
-        self, *, disputer_role: str, disputer_mean: float, claim: ClaimRec, gap: float
+        self,
+        *,
+        disputer_role: str,
+        disputer_unit: str,
+        disputer_mean: float,
+        claim: ClaimRec,
+        gap: float,
     ) -> bool:
-        # Anyone disputes a rival unit's claim if it diverges at all past a
-        # softened gap; sceptics are the most aggressive.
         if claim.role == "oracle":
             return False
-        effective_gap = gap * (0.5 if disputer_role == "sceptic" else 1.0)
+        # Never attack your own coalition.
+        if self._allied(disputer_unit, claim.unit):
+            return False
+        # Power tilt: strong factions escalate (lower the gap), weak concede.
+        edge = self._power.get(disputer_unit, 0.0) - self._power.get(claim.unit, 0.0)
+        role_factor = 0.5 if disputer_role == "sceptic" else 1.0
+        effective_gap = max(0.0, gap * role_factor - self._escalation * edge)
         return abs(disputer_mean - claim.confidence) >= effective_gap
 
+    def resolve_outcome(self, *, claim: ClaimRec, ground_truth: bool | None) -> bool:
+        outcome = super().resolve_outcome(claim=claim, ground_truth=ground_truth)
+        self._power[claim.unit] = self._power.get(claim.unit, 0.0) + (1.0 if outcome else -1.0)
+        self._timeline.append({"unit": claim.unit, "power": self._power[claim.unit]})
+        return outcome
+
+    def state(self) -> dict[str, object]:
+        return {
+            "power": dict(self._power),
+            "coalitions": {u: self._coalition(u) for u in self._power},
+            "power_timeline": list(self._timeline),
+        }
+
 
 class Crowd(Interaction):
     """Large, low-authority population; synthesists aggregate; few disputes."""
@@ -151,7 +206,13 @@ class Crowd(Interaction):
         return [c.kid for c in peers[:3]]
 
     def should_dispute(
-        self, *, disputer_role: str, disputer_mean: float, claim: ClaimRec, gap: float
+        self,
+        *,
+        disputer_role: str,
+        disputer_unit: str,
+        disputer_mean: float,
+        claim: ClaimRec,
+        gap: float,
     ) -> bool:
         # The crowd rarely disputes; only sceptics, only on very wide gaps.
         if disputer_role != "sceptic":

{hypermind-0.14.0 → hypermind-0.15.0}/src/hypermind/orgs/model.py

@@ -109,6 +109,7 @@ class DynamicsConfig:
     vouch_juniors: bool = True
     evolve: bool = True
     interaction: str = "cooperative"
+    mode: str = "scripted"  # scripted | deliberator (real mind-layer policies)
     # Convergence-driven stopping (used when run() is called without rounds=).
     convergence_threshold: float = 0.02  # posterior variance <= this = consensus
     convergence_patience: int = 2  # consecutive rounds required to declare a stop
@@ -130,6 +131,8 @@ class DynamicsConfig:
             raise ValueError(
                 f"interaction must be one of {sorted(VALID_INTERACTIONS)}, got {self.interaction!r}"
             )
+        if self.mode not in ("scripted", "deliberator"):
+            raise ValueError(f"mode must be 'scripted' or 'deliberator', got {self.mode!r}")
 
 
 @dataclass(frozen=True)

hypermind-0.15.0/src/hypermind/orgs/receipt.py

@@ -0,0 +1,101 @@
+"""Verifiable decision records (#161) — SCITT-style receipt export.
+
+The moat: emit a **tamper-evident, self-verifying** record of how a simulated
+decision was reached — the signed claims (referenced by their content-address
+``kid``), the citation DAG, the dispute ledger, the resolution outcomes, and
+the final reputation — that a third party can verify offline.
+
+Each claim's ``kid`` is the content hash of its COSE-signed statement on the
+HyperMind ledger, so referencing kids binds the receipt to signed content; a
+SHA-256 digest over the canonical record makes the whole decision tamper-
+evident. :func:`verify_receipt` recomputes the digest and checks structural
+integrity (every cited/disputed target exists). Change any field → the digest
+no longer matches → verification fails.
+
+Full COSE-signature + transparency-Merkle-proof replay via
+``reference_verifier`` is a follow-up; this layer only *reads/exports* and
+never touches security-tagged code.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from hypermind.orgs.report import OrgReport
+
+RECEIPT_VERSION = 1
+
+
+def _canonical(obj: Any) -> bytes:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), default=str).encode()
+
+
+def _digest(record: dict[str, Any]) -> str:
+    return hashlib.sha256(_canonical(record)).hexdigest()
+
+
+def build_receipt(report: OrgReport) -> dict[str, Any]:
+    """Assemble a tamper-evident receipt from a finished report."""
+    record = {
+        "version": RECEIPT_VERSION,
+        "org": report.org,
+        "topic": report.topic,
+        "rounds": report.rounds,
+        "interaction": report.interaction,
+        "stop_reason": report.stop_reason,
+        "claims": [
+            {
+                "kid": c.get("kid_hex"),
+                "by": c.get("label"),
+                "round": c.get("round"),
+                "confidence": c.get("confidence"),
+                "outcome": c.get("outcome"),
+            }
+            for c in report.claims
+        ],
+        "citations": [list(e) for e in report.citations],
+        "disputes": [
+            {"target": d.get("target"), "disputer": d.get("disputer")} for d in report.disputes
+        ],
+        "reputation": {s.label: s.reputation for s in report.standings},
+    }
+    return {**record, "digest": _digest(record)}
+
+
+@dataclass(frozen=True)
+class VerifyResult:
+    valid: bool
+    errors: list[str]
+
+
+def verify_receipt(receipt: dict[str, Any]) -> VerifyResult:
+    """Verify a receipt offline: digest integrity + structural consistency."""
+    errors: list[str] = []
+    record = {k: v for k, v in receipt.items() if k != "digest"}
+
+    # 1. Integrity: the digest must match the canonical record.
+    expected = _digest(record)
+    if receipt.get("digest") != expected:
+        errors.append("digest mismatch — record has been altered")
+
+    if record.get("version") != RECEIPT_VERSION:
+        errors.append(f"unsupported receipt version {record.get('version')!r}")
+
+    # 2. Structure: every cited / disputed target must be a known claim kid.
+    kids = {c.get("kid") for c in record.get("claims", [])}
+    for citer, target in record.get("citations", []):
+        if target not in kids:
+            errors.append(f"citation by {citer!r} targets unknown claim {target!r}")
+    for d in record.get("disputes", []):
+        # Dispute targets are recorded by member label (target_by) in the report;
+        # accept either a kid or a known author label.
+        tgt = d.get("target")
+        authors = {c.get("by") for c in record.get("claims", [])}
+        if tgt not in kids and tgt not in authors:
+            errors.append(f"dispute targets unknown claim/member {tgt!r}")
+
+    return VerifyResult(valid=not errors, errors=errors)

{hypermind-0.14.0 → hypermind-0.15.0}/src/hypermind/orgs/report.py

@@ -41,6 +41,8 @@ class OrgReport:
     scorecard: dict[str, Any] = field(default_factory=dict)
     stop_reason: str = "fixed"  # fixed | converged | polarized | max_rounds
     events: list[dict[str, Any]] = field(default_factory=list)  # applied interventions
+    interaction_state: dict[str, Any] = field(default_factory=dict)  # e.g. power balance
+    decisions: list[dict[str, Any]] = field(default_factory=list)  # deliberator-mode trace
 
     # ---- derived views -------------------------------------------------
 
@@ -61,6 +63,23 @@ class OrgReport:
             "disputes": len(self.disputes),
         }
 
+    def tool_calls(self) -> list[dict[str, Any]]:
+        """Every tool call agents made, flattened with the calling member."""
+        out: list[dict[str, Any]] = []
+        for c in self.claims:
+            for tc in c.get("tool_calls", []):
+                out.append({"by": c.get("label"), **tc})
+        return out
+
+    def export_receipt(self) -> dict[str, Any]:
+        """A tamper-evident, offline-verifiable record of this decision.
+
+        See :func:`hypermind.orgs.receipt.verify_receipt`.
+        """
+        from hypermind.orgs.receipt import build_receipt
+
+        return build_receipt(self)
+
     # ---- serialisation -------------------------------------------------
 
     def to_dict(self) -> dict[str, Any]: