PyPI - hypermind - Versions diffs - 0.11.0__py3-none-any.whl - Mend

hypermind 0.11.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (181) hide show

hmctl/__init__.py +7 -0
hmctl/cli.py +947 -0
hypermind/__init__.py +208 -0
hypermind/_deprecations.py +108 -0
hypermind/agent.py +2896 -0
hypermind/agent_card.py +127 -0
hypermind/api/__init__.py +32 -0
hypermind/api/app.py +686 -0
hypermind/capability.py +923 -0
hypermind/consult.py +493 -0
hypermind/consult_bias.py +112 -0
hypermind/contract_net.py +219 -0
hypermind/crypto/__init__.py +21 -0
hypermind/crypto/cose_encrypt.py +126 -0
hypermind/crypto/dkg.py +246 -0
hypermind/crypto/domain.py +59 -0
hypermind/crypto/frost.py +771 -0
hypermind/crypto/hashing.py +38 -0
hypermind/crypto/hlc.py +163 -0
hypermind/crypto/hpke.py +277 -0
hypermind/crypto/kms.py +196 -0
hypermind/crypto/kms_backends/__init__.py +56 -0
hypermind/crypto/kms_backends/aws.py +128 -0
hypermind/crypto/kms_backends/azure.py +114 -0
hypermind/crypto/kms_backends/gcp.py +97 -0
hypermind/crypto/kms_backends/vault.py +120 -0
hypermind/crypto/namespace_root.py +204 -0
hypermind/crypto/pq.py +152 -0
hypermind/crypto/room_epoch.py +97 -0
hypermind/crypto/signing.py +245 -0
hypermind/deliberation.py +355 -0
hypermind/did_web.py +256 -0
hypermind/dispute.py +858 -0
hypermind/errors.py +218 -0
hypermind/eval/__init__.py +49 -0
hypermind/eval/calibration.py +307 -0
hypermind/eval/comparison.py +251 -0
hypermind/eval/replay.py +202 -0
hypermind/eval/swarm_iq.py +718 -0
hypermind/knowledge/__init__.py +17 -0
hypermind/knowledge/citation_graph.py +141 -0
hypermind/knowledge/correlated_agreement.py +167 -0
hypermind/knowledge/embedding_registry.py +115 -0
hypermind/knowledge/kernel_store.py +197 -0
hypermind/knowledge/rekor.py +173 -0
hypermind/knowledge/reputation.py +364 -0
hypermind/knowledge/swarm_memory.py +523 -0
hypermind/knowledge/transparency.py +409 -0
hypermind/mcp/__init__.py +60 -0
hypermind/mcp/bridge.py +151 -0
hypermind/mcp/client.py +142 -0
hypermind/mcp/provenance.py +214 -0
hypermind/mcp/relata_tools.py +152 -0
hypermind/mcp/server.py +248 -0
hypermind/mcp/transport.py +206 -0
hypermind/mind/__init__.py +150 -0
hypermind/mind/active.py +234 -0
hypermind/mind/belief.py +369 -0
hypermind/mind/deliberator.py +625 -0
hypermind/mind/diversity.py +144 -0
hypermind/mind/evolve.py +184 -0
hypermind/mind/federation.py +154 -0
hypermind/mind/goals.py +117 -0
hypermind/mind/integration.py +190 -0
hypermind/mind/mediator.py +74 -0
hypermind/mind/memory_store.py +129 -0
hypermind/mind/policy.py +307 -0
hypermind/mind/records.py +260 -0
hypermind/mind/roles.py +190 -0
hypermind/mind/sybil_guard.py +41 -0
hypermind/mind/world_model.py +166 -0
hypermind/namespace.py +515 -0
hypermind/namespace_policy.py +254 -0
hypermind/observability/__init__.py +25 -0
hypermind/observability/asgi.py +214 -0
hypermind/observability/cost.py +277 -0
hypermind/observability/otel_export.py +200 -0
hypermind/observability/recorder.py +344 -0
hypermind/observability/swarm_trace.py +438 -0
hypermind/pin_policy.py +116 -0
hypermind/py.typed +0 -0
hypermind/responders/__init__.py +87 -0
hypermind/responders/anthropic.py +159 -0
hypermind/responders/base.py +162 -0
hypermind/responders/openai.py +199 -0
hypermind/responders/router.py +254 -0
hypermind/responders/structured.py +287 -0
hypermind/responders/tools.py +444 -0
hypermind/revocation.py +270 -0
hypermind/rule_ids.py +135 -0
hypermind/schemas/encrypted_statement.cddl +28 -0
hypermind/schemas/namespace_accept.cddl +20 -0
hypermind/schemas/namespace_create.cddl +25 -0
hypermind/schemas/namespace_founding_attest.cddl +30 -0
hypermind/schemas/namespace_invite.cddl +22 -0
hypermind/schemas/wire-v0.1.cddl +73 -0
hypermind/simlab/__init__.py +15 -0
hypermind/simlab/_persona_registry.py +93 -0
hypermind/simlab/_scenario_impl.py +2778 -0
hypermind/simlab/app.py +2538 -0
hypermind/simlab/backends/__init__.py +27 -0
hypermind/simlab/backends/anchor.py +88 -0
hypermind/simlab/backends/local.py +32 -0
hypermind/simlab/backends/server.py +79 -0
hypermind/simlab/cli_command.py +108 -0
hypermind/simlab/config.py +106 -0
hypermind/simlab/deployment.py +26 -0
hypermind/simlab/knowledge.py +716 -0
hypermind/simlab/learning.py +295 -0
hypermind/simlab/modes/__init__.py +115 -0
hypermind/simlab/modes/_eval_real_llm.py +373 -0
hypermind/simlab/modes/aar.py +611 -0
hypermind/simlab/modes/backtest.py +610 -0
hypermind/simlab/modes/binary_forecast.py +69 -0
hypermind/simlab/modes/conformance.py +1869 -0
hypermind/simlab/modes/evaluation.py +2271 -0
hypermind/simlab/modes/governance.py +648 -0
hypermind/simlab/modes/redteam.py +534 -0
hypermind/simlab/modes/tabletop.py +797 -0
hypermind/simlab/modes/tournament.py +448 -0
hypermind/simlab/modes/whatif.py +523 -0
hypermind/simlab/namespace.py +125 -0
hypermind/simlab/personas.py +477 -0
hypermind/simlab/prompt_generator.py +172 -0
hypermind/simlab/question_sets/geopolitics_q20.json +122 -0
hypermind/simlab/question_sets/governance_q5.json +67 -0
hypermind/simlab/question_sets/msft_outlook_q10.json +62 -0
hypermind/simlab/question_sets/whatif_q3.json +38 -0
hypermind/simlab/registry.py +325 -0
hypermind/simlab/runner.py +239 -0
hypermind/simlab/scenario.py +147 -0
hypermind/simlab/swarms.py +180 -0
hypermind/simlab/tool_handlers/__init__.py +4 -0
hypermind/simlab/tool_handlers/alpha_vantage.py +39 -0
hypermind/simlab/tool_handlers/brave.py +46 -0
hypermind/simlab/tool_handlers/newsapi.py +50 -0
hypermind/simlab/tool_handlers/openweather.py +46 -0
hypermind/simlab/tool_handlers/pinecone.py +52 -0
hypermind/simlab/tool_handlers/qdrant.py +57 -0
hypermind/simlab/tool_handlers/query_knowledge_base.py +21 -0
hypermind/simlab/tool_handlers/relata_recall.py +61 -0
hypermind/simlab/tool_handlers/retrieve_document.py +21 -0
hypermind/simlab/tool_handlers/serper.py +46 -0
hypermind/simlab/tool_handlers/tavily.py +53 -0
hypermind/simlab/tool_handlers/weaviate.py +65 -0
hypermind/simlab/tool_handlers/wikipedia.py +64 -0
hypermind/simlab/tool_handlers/wolfram.py +48 -0
hypermind/simlab/tool_handlers/yahoo_finance.py +49 -0
hypermind/simlab/tool_registry.py +568 -0
hypermind/simlab/topic_adapter.py +338 -0
hypermind/simlab/topic_questions.py +259 -0
hypermind/storage/__init__.py +69 -0
hypermind/storage/backend.py +71 -0
hypermind/storage/relata.py +245 -0
hypermind/storage/sqlite.py +258 -0
hypermind/sync.py +191 -0
hypermind/tal.py +175 -0
hypermind/tasks.py +334 -0
hypermind/testing.py +16 -0
hypermind/tools/__init__.py +32 -0
hypermind/tools/registry.py +61 -0
hypermind/transport/__init__.py +22 -0
hypermind/transport/anti_entropy.py +708 -0
hypermind/transport/bus.py +206 -0
hypermind/transport/knows_delta.py +204 -0
hypermind/transport/libp2p.py +298 -0
hypermind/transport/placement.py +58 -0
hypermind/transport/tcp.py +797 -0
hypermind/transport/tls_profile.py +417 -0
hypermind/types.py +59 -0
hypermind/uncertainty.py +222 -0
hypermind/wire.py +897 -0
hypermind/workflow/__init__.py +72 -0
hypermind/workflow/engine.py +655 -0
hypermind/workflow/plan.py +182 -0
hypermind/workflow/repair.py +203 -0
hypermind-0.11.0.dist-info/METADATA +524 -0
hypermind-0.11.0.dist-info/RECORD +181 -0
hypermind-0.11.0.dist-info/WHEEL +4 -0
hypermind-0.11.0.dist-info/entry_points.txt +2 -0
hypermind-0.11.0.dist-info/licenses/LICENSE +201 -0

hypermind/mind/records.py ADDED Viewed

@@ -0,0 +1,260 @@
+"""Mind collaboration records — intent, trace, dissent.
+These are *application-layer* records carried inside the existing
+``SEAL`` SignedStatement payload. We deliberately avoid extending the
+COSE/CBOR wire format (which would require an envelope_schema_hash bump,
+v0.2 wire-version negotiation, reference_verifier sync, and updated
+Appendix Z conformance vectors).
+Carrying mind-records as typed payloads keeps:
+  - A-ALG-BOUND intact (record_type stays "SEAL", every discriminator
+    in the protected header)
+  - reference_verifier interop intact
+  - transparency-log auditability intact (each is sealed and cosigned
+    via TransparencyService.append_and_cosign)
+  - reputation accountability intact (signed by issuer, citeable like
+    any other claim)
+A future v1 wire-version may promote these to first-class record_types;
+the on-disk codec defined here will be the canonical encoding.
+Schema (CBOR map, deterministic):
+    { 0: <kind str>, 1: <topic str>, 2: <body map>, 3: <hlc_ms int>,
+      4: <issuer_kid bytes>, 5: <version int> }
+"""
+from __future__ import annotations
+import hashlib
+from dataclasses import dataclass, field
+from typing import Any, Literal
+import cbor2
+def make_target_kid_commitment(target_kid: bytes) -> bytes:
+    """P3-02: Compute the SHA-256 commitment over a target kid.
+    Use this to populate ``IntentRecord.target_kid_commitment`` when
+    you want to announce a dispute intent without revealing the full
+    target kid on the gossip bus.
+    """
+    return hashlib.sha256(target_kid).digest()
+MIND_RECORD_VERSION = 1
+MindRecordKind = Literal["intent", "trace", "dissent"]
+# DoS gate: oversize CBOR payloads are rejected before parsing. Mind records
+# are small typed envelopes; 64 KiB is comfortable headroom over the largest
+# realistic intent/trace/dissent body.
+MAX_MIND_RECORD_BYTES = 64 * 1024
+_KEY_KIND = 0
+_KEY_TOPIC = 1
+_KEY_BODY = 2
+_KEY_HLC_MS = 3
+_KEY_ISSUER_KID = 4
+_KEY_VERSION = 5
+@dataclass(frozen=True)
+class IntentRecord:
+    """Agent announces an upcoming action so peers can pre-stage / dedupe."""
+    topic: str
+    action: str  # one of "consult", "publish", "dispute", ...
+    target_kid: bytes | None = None  # for dispute intents
+    expected_completion_ms: int | None = None
+    note: str = ""
+    # P3-02: privacy-preserving commitment to the target kid.
+    # When set, this is SHA-256(target_kid) so peers can match dispute
+    # intents against claims they know without exposing the full kid to
+    # agents that don't need it. If both target_kid and
+    # target_kid_commitment are set, target_kid takes precedence for
+    # local use; target_kid_commitment is what is broadcast on the wire.
+    target_kid_commitment: bytes | None = None
+    kind: str = field(default="intent", init=False)
+@dataclass(frozen=True)
+class TraceRecord:
+    """Reasoning trace for a published claim — the citations that shaped it.
+    First-class on-wire: makes the citation graph queryable from any
+    transparency-log audit. Closes failure-modes.md:49 (citation-graph
+    attack — citations were previously local-store only).
+    """
+    topic: str
+    claim_kid: bytes  # the claim this trace explains
+    parent_kids: tuple[bytes, ...]
+    consult_kids: tuple[bytes, ...] = ()
+    note: str = ""
+    kind: str = field(default="trace", init=False)
+@dataclass(frozen=True)
+class DissentRecord:
+    """Lightweight pre-dispute signal: 'I see this differently'.
+    No bond posted, no FSM transition. Surfaces minority disagreement
+    before it escalates to a full bonded dispute — closes the herding
+    failure mode (failure-modes.md:17) by making divergence visible
+    early. Carries an optional reasoning note so peers can adjudicate
+    whether to weight it.
+    """
+    topic: str
+    target_kid: bytes
+    own_posterior: float
+    note: str = ""
+    margin: float = 0.0  # |own_posterior - peer_posterior|
+    kind: str = field(default="dissent", init=False)
+# -----------------------------------------------------------------------
+# Encoding
+# -----------------------------------------------------------------------
+def encode_mind_record(
+    record: IntentRecord | TraceRecord | DissentRecord,
+    *,
+    issuer_kid: bytes,
+    hlc_ms: int,
+) -> bytes:
+    """Serialise a mind record as deterministic CBOR for SEAL payload."""
+    if isinstance(record, IntentRecord):
+        body: dict[str, Any] = {
+            "action": record.action,
+            "note": record.note,
+        }
+        if record.target_kid is not None:
+            body["target_kid"] = record.target_kid
+        if record.expected_completion_ms is not None:
+            body["expected_completion_ms"] = record.expected_completion_ms
+        # P3-02: include the commitment if present
+        if record.target_kid_commitment is not None:
+            body["target_kid_commitment"] = record.target_kid_commitment
+    elif isinstance(record, TraceRecord):
+        body = {
+            "claim_kid": record.claim_kid,
+            "parent_kids": list(record.parent_kids),
+            "consult_kids": list(record.consult_kids),
+            "note": record.note,
+        }
+    elif isinstance(record, DissentRecord):
+        body = {
+            "target_kid": record.target_kid,
+            "own_posterior": record.own_posterior,
+            "margin": record.margin,
+            "note": record.note,
+        }
+    else:  # pragma: no cover - typeguard
+        raise TypeError(f"unknown mind record type: {type(record).__name__}")
+    envelope = {
+        _KEY_KIND: record.kind,
+        _KEY_TOPIC: record.topic,
+        _KEY_BODY: body,
+        _KEY_HLC_MS: int(hlc_ms),
+        _KEY_ISSUER_KID: bytes(issuer_kid),
+        _KEY_VERSION: MIND_RECORD_VERSION,
+    }
+    return cbor2.dumps(envelope, canonical=True)
+def decode_mind_record(
+    raw: bytes,
+    *,
+    expected_signer_kid: bytes,
+) -> tuple[IntentRecord | TraceRecord | DissentRecord, bytes, int]:
+    """Decode a mind-record payload. Returns (record, issuer_kid, hlc_ms).
+    The ``expected_signer_kid`` is the kid of the outer SignedStatement
+    signer; it MUST match the embedded ``issuer_kid`` to prevent a kid
+    spoofing attack where a valid signer wraps a payload that claims a
+    different agent as issuer.
+    Raises ``ValueError`` on malformed/unsupported records, oversize
+    payloads, or issuer_kid mismatch.
+    """
+    if len(raw) > MAX_MIND_RECORD_BYTES:
+        raise ValueError(f"mind record too large: {len(raw)} > {MAX_MIND_RECORD_BYTES}")
+    try:
+        env = cbor2.loads(raw)
+    except Exception as e:
+        raise ValueError(f"mind record decode: not CBOR: {e}") from e
+    if not isinstance(env, dict):
+        raise ValueError("mind record decode: not a map")
+    version = env.get(_KEY_VERSION)
+    if version != MIND_RECORD_VERSION:
+        raise ValueError(f"mind record decode: unsupported version {version!r}")
+    kind = env.get(_KEY_KIND)
+    topic = env.get(_KEY_TOPIC)
+    body = env.get(_KEY_BODY) or {}
+    hlc_ms = int(env.get(_KEY_HLC_MS, 0))
+    issuer_kid = env.get(_KEY_ISSUER_KID, b"")
+    if not isinstance(topic, str) or not isinstance(body, dict):
+        raise ValueError("mind record decode: malformed topic/body")
+    if not isinstance(issuer_kid, (bytes, bytearray)):
+        raise ValueError("mind record decode: issuer_kid must be bytes")
+    issuer_kid_bytes = bytes(issuer_kid)
+    if issuer_kid_bytes != bytes(expected_signer_kid):
+        raise ValueError(
+            "issuer_kid mismatch: payload claims "
+            f"{issuer_kid_bytes[:8].hex()}, signer is "
+            f"{bytes(expected_signer_kid)[:8].hex()}"
+        )
+    if kind == "intent":
+        raw_commitment = body.get("target_kid_commitment")
+        rec: Any = IntentRecord(
+            topic=topic,
+            action=str(body.get("action", "")),
+            target_kid=body.get("target_kid"),
+            expected_completion_ms=body.get("expected_completion_ms"),
+            note=str(body.get("note", "")),
+            # P3-02: decode target_kid_commitment if present
+            target_kid_commitment=(
+                bytes(raw_commitment) if isinstance(raw_commitment, (bytes, bytearray)) else None
+            ),
+        )
+    elif kind == "trace":
+        rec = TraceRecord(
+            topic=topic,
+            claim_kid=bytes(body.get("claim_kid", b"")),
+            parent_kids=tuple(bytes(p) for p in body.get("parent_kids", ())),
+            consult_kids=tuple(bytes(c) for c in body.get("consult_kids", ())),
+            note=str(body.get("note", "")),
+        )
+    elif kind == "dissent":
+        rec = DissentRecord(
+            topic=topic,
+            target_kid=bytes(body.get("target_kid", b"")),
+            own_posterior=float(body.get("own_posterior", 0.0)),
+            margin=float(body.get("margin", 0.0)),
+            note=str(body.get("note", "")),
+        )
+    else:
+        raise ValueError(f"mind record decode: unknown kind {kind!r}")
+    return rec, issuer_kid_bytes, hlc_ms
+def is_mind_record(raw: bytes) -> bool:
+    """Cheap discriminator — does this look like a mind record envelope?"""
+    if len(raw) > MAX_MIND_RECORD_BYTES:
+        return False
+    try:
+        env = cbor2.loads(raw)
+    except Exception:
+        return False
+    return (
+        isinstance(env, dict)
+        and env.get(_KEY_VERSION) == MIND_RECORD_VERSION
+        and env.get(_KEY_KIND) in ("intent", "trace", "dissent")
+    )

hypermind/mind/roles.py ADDED Viewed

@@ -0,0 +1,190 @@
+"""Role specialisation — Scout, Sceptic, Generalist, Synthesist, Mediator, Oracle.
+A Role is a declarative bundle of (policies, caveats) that composes
+with the existing CapToken chain. Picking a role for an agent is the
+fastest path to a swarm of differentiated specialists rather than a
+swarm of clones.
+Spec: docs/spec/20-swarm-intelligence.md §20.2.
+"""
+from __future__ import annotations
+from dataclasses import dataclass, field
+from enum import StrEnum
+from hypermind.capability import Caveat
+from hypermind.mind.policy import (
+    ActionPolicy,
+    CheckpointOnSignalGain,
+    ConsultOnDisagreement,
+    DisputeOnContradiction,
+    PublishWhenConfident,
+)
+class RoleKind(StrEnum):
+    SCOUT = "scout"
+    SCEPTIC = "sceptic"
+    GENERALIST = "generalist"
+    SYNTHESIST = "synthesist"
+    MEDIATOR = "mediator"
+    ORACLE = "oracle"
+@dataclass(frozen=True)
+class Role:
+    """A role bundle — policies + caveats + descriptive metadata."""
+    kind: RoleKind
+    policies: tuple[ActionPolicy, ...]
+    caveats: tuple[Caveat, ...] = ()
+    description: str = ""
+    publishes_primary: bool = True  # False for Mediator/Oracle (they don't publish raw claims)
+    def policy_list(self) -> list[ActionPolicy]:
+        return list(self.policies)
+    def caveat_list(self) -> list[Caveat]:
+        return list(self.caveats)
+# ---------------------------------------------------------------------------
+# Built-in roles
+# ---------------------------------------------------------------------------
+def scout(*, topic: str = "*") -> Role:
+    """Low-confidence threshold, high consult frequency, broad caveat."""
+    return Role(
+        kind=RoleKind.SCOUT,
+        policies=(
+            PublishWhenConfident(threshold=0.65, priority=40),
+            ConsultOnDisagreement(divergence=0.15, priority=55),
+            CheckpointOnSignalGain(kl_threshold=0.05, priority=30),
+        ),
+        caveats=(Caveat.topic(topic), Caveat.rate("60/min")),
+        description="early-warning, broad coverage, frequent consults",
+    )
+def sceptic(*, topic: str = "*") -> Role:
+    """Aggressive disputes, high publish bar."""
+    return Role(
+        kind=RoleKind.SCEPTIC,
+        policies=(
+            PublishWhenConfident(threshold=0.92, priority=30),
+            DisputeOnContradiction(min_gap=0.3, min_rep_delta=0.10, priority=70),
+            ConsultOnDisagreement(divergence=0.25, priority=40),
+        ),
+        caveats=(Caveat.topic(topic), Caveat.rate("30/min")),
+        description="contrarian; raises the bar on consensus",
+    )
+def generalist(*, topic: str = "*") -> Role:
+    """Balanced default."""
+    return Role(
+        kind=RoleKind.GENERALIST,
+        policies=(
+            PublishWhenConfident(threshold=0.8, priority=50),
+            ConsultOnDisagreement(divergence=0.3, priority=40),
+            DisputeOnContradiction(min_gap=0.4, min_rep_delta=0.15, priority=60),
+            CheckpointOnSignalGain(kl_threshold=0.1, priority=30),
+        ),
+        caveats=(Caveat.topic(topic),),
+        description="balanced default; the v0.10 mind layer's behaviour",
+    )
+def synthesist(*, topic: str = "*") -> Role:
+    """Aggregator only — caveat enforces synthesis claim type."""
+    return Role(
+        kind=RoleKind.SYNTHESIST,
+        policies=(
+            PublishWhenConfident(threshold=0.85, priority=40),
+            ConsultOnDisagreement(divergence=0.2, priority=55),
+        ),
+        caveats=(
+            Caveat.topic(topic),
+            Caveat.claim_type("synthesis"),
+            Caveat.rate("10/min"),
+        ),
+        description="only publishes synthesis claims; ≥3 parents required (enforced by application)",
+    )
+def mediator(*, topic: str = "*") -> Role:
+    """Adjudication role; cannot publish primary claims (caveat-enforced)."""
+    return Role(
+        kind=RoleKind.MEDIATOR,
+        policies=(DisputeOnContradiction(min_gap=0.5, min_rep_delta=0.2, priority=80),),
+        caveats=(
+            Caveat.topic(topic),
+            Caveat.claim_type("synthesis"),  # mediators may only publish summaries
+        ),
+        description="VRF-selected adjudicator; uses select_mediator() for picks",
+        publishes_primary=False,
+    )
+def oracle(*, topic: str = "*") -> Role:
+    """Ground-truth resolver only — publishes oracle_resolution claims."""
+    return Role(
+        kind=RoleKind.ORACLE,
+        policies=(),  # oracle doesn't deliberate; it resolves
+        caveats=(
+            Caveat.topic(topic),
+            Caveat.claim_type("oracle_resolution"),
+        ),
+        description="closes the loop; not a deliberator",
+        publishes_primary=False,
+    )
+_BUILTIN: dict[str, callable] = {
+    "scout": scout,
+    "sceptic": sceptic,
+    "generalist": generalist,
+    "synthesist": synthesist,
+    "mediator": mediator,
+    "oracle": oracle,
+}
+def role_by_name(name: str, *, topic: str = "*") -> Role:
+    """Look up a built-in role by its lowercase name."""
+    if name not in _BUILTIN:
+        raise ValueError(f"unknown role {name!r}; valid: {sorted(_BUILTIN)}")
+    return _BUILTIN[name](topic=topic)
+# ---------------------------------------------------------------------------
+# Composition — assemble a swarm spec
+# ---------------------------------------------------------------------------
+@dataclass
+class SwarmComposition:
+    """A swarm spec — counts per role. Used by the harness + examples."""
+    counts: dict[RoleKind, int] = field(default_factory=dict)
+    @classmethod
+    def of(cls, **kwargs: int) -> SwarmComposition:
+        """``SwarmComposition.of(scout=3, generalist=2, oracle=1)``."""
+        out = cls()
+        for k, n in kwargs.items():
+            out.counts[RoleKind(k)] = int(n)
+        return out
+    def total(self) -> int:
+        return sum(self.counts.values())
+    def expand(self, *, topic: str = "*") -> list[Role]:
+        """Return the flat list of roles per the configured counts."""
+        out: list[Role] = []
+        for kind, n in self.counts.items():
+            for _ in range(int(n)):
+                out.append(role_by_name(kind.value, topic=topic))
+        return out

hypermind/mind/sybil_guard.py ADDED Viewed

@@ -0,0 +1,41 @@
+"""SybilGuard — cap influence of new agents in deliberator decisions.
+Failure mode (design/failure-modes.md:59-78): a vouched newcomer can
+inject up to ~30 claims before the calibration loop detects bad
+predictions. With N pre-built sybils, that scales to N × 30
+undetected injections. The vouch cap (5% of voucher α) is the
+network-side defence; this is the agent-side defence — the
+*deliberator* of an honest agent should refuse to give a newcomer
+full weight in routing/synthesis until they've earned a track record
+of resolved outcomes.
+API mirrors the existing 5%-of-α vouch cap pattern in
+src/hypermind/knowledge/reputation.py:136-157.
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+@dataclass
+class SybilGuard:
+    """Cap an agent's effective weight by their observation count.
+    ``min_observations`` is the threshold for full weight. Below that,
+    weight is linearly attenuated down to ``floor_weight``.
+    """
+    min_observations: int = 30
+    floor_weight: float = 0.05
+    def effective_weight(self, raw_weight: float, n_observations: int) -> float:
+        if n_observations >= self.min_observations:
+            return raw_weight
+        ratio = max(0, n_observations) / max(1, self.min_observations)
+        capped = self.floor_weight + (1.0 - self.floor_weight) * ratio
+        return raw_weight * capped
+    def is_advisory_only(self, n_observations: int) -> bool:
+        """True when the agent's weight is below 50% of full."""
+        return n_observations < (self.min_observations // 2)

hypermind/mind/world_model.py ADDED Viewed

@@ -0,0 +1,166 @@
+"""WorldModel + LookaheadPolicy — model-based deliberation.
+Agents that *plan* against an internal predictive model dramatically
+outperform reactive ones (cf. MuZero/Dreamer). We expose a Protocol
+so production deployments can swap in any predictor (LLM-backed,
+Bayesian, learned model). The sandbox impl is a Beta predictor over
+the agent's own (action, outcome) history.
+Spec: docs/spec/20-swarm-intelligence.md §20.5.
+"""
+from __future__ import annotations
+import time
+from dataclasses import dataclass, field
+from typing import Protocol, runtime_checkable
+from hypermind.mind.policy import (
+    ActionDecision,
+    ActionKind,
+    ActionPolicy,
+    PolicyContext,
+)
+@dataclass(frozen=True)
+class ImaginedOutcome:
+    """A predicted future state after a hypothetical action."""
+    posterior: float  # P(positive outcome) under this action
+    confidence: float  # how confident the world model is in the prediction
+@runtime_checkable
+class WorldModel(Protocol):
+    """Pluggable predictive model. Production may wire an LLM."""
+    def predict(self, action: ActionKind, ctx: PolicyContext) -> ImaginedOutcome: ...
+    def update_with_outcome(
+        self, action: ActionKind, ctx: PolicyContext, observed: float
+    ) -> None: ...
+# ---------------------------------------------------------------------------
+# Default sandbox impl — Beta predictor
+# ---------------------------------------------------------------------------
+@dataclass
+class BetaWorldModel:
+    """Per-action Beta posterior over P(good outcome).
+    Each action kind has its own (alpha, beta). The model is a thin
+    self-supervised learner: when an outcome is observed, the matching
+    bucket updates. Confidence is `1 - 1 / (alpha + beta)` — saturates
+    toward 1.0 as data accumulates (more data ⇒ sharper posterior ⇒
+    "more confident"). With the Beta(1,1) prior, confidence starts at
+    0.5, matching the prior uncertainty.
+    """
+    _state: dict[ActionKind, tuple[float, float]] = field(default_factory=dict)
+    def _get(self, action: ActionKind) -> tuple[float, float]:
+        return self._state.get(action, (1.0, 1.0))
+    def predict(self, action: ActionKind, ctx: PolicyContext) -> ImaginedOutcome:
+        a, b = self._get(action)
+        mean = a / (a + b)
+        # Boost predictions when the agent's posterior on the topic
+        # already supports this action (e.g. high posterior + publish ⇒ high VOI).
+        topic_post = (ctx.working_memory.get("posteriors") or {}).get(ctx.topic)
+        if topic_post is not None and action is ActionKind.PUBLISH:
+            mean = 0.5 * mean + 0.5 * topic_post
+        confidence = 1.0 - 1.0 / (a + b)
+        return ImaginedOutcome(posterior=mean, confidence=confidence)
+    def update_with_outcome(self, action: ActionKind, ctx: PolicyContext, observed: float) -> None:
+        a, b = self._get(action)
+        # observed ∈ [0, 1]; treat as fractional outcome.
+        a += float(observed)
+        b += 1.0 - float(observed)
+        self._state[action] = (a, b)
+# ---------------------------------------------------------------------------
+# LookaheadPolicy — N-step planning with a per-tick budget
+# ---------------------------------------------------------------------------
+@dataclass
+class LookaheadPolicy(ActionPolicy):
+    """Plan ``depth`` steps with the world_model; pick the highest-EV action.
+    For each candidate action (publish / consult / dispute / checkpoint),
+    estimate the expected value-of-information (EVI) under the model.
+    Highest EVI wins; ties broken by priority.
+    Per-tick budget is a soft time cap; the policy returns the best
+    decision found so far if the budget is exhausted.
+    """
+    world_model: WorldModel = field(default_factory=BetaWorldModel)
+    depth: int = 2
+    budget_ms: float = 10.0
+    priority: int = 65
+    candidates: tuple[ActionKind, ...] = (
+        ActionKind.PUBLISH,
+        ActionKind.CONSULT,
+        ActionKind.CHECKPOINT,
+    )
+    def decide(self, ctx: PolicyContext) -> ActionDecision | None:
+        deadline = time.perf_counter() + (self.budget_ms / 1000.0)
+        best: tuple[float, ActionKind] | None = None
+        for action in self.candidates:
+            if time.perf_counter() >= deadline:
+                break
+            evi = self._evi(action, ctx, depth=self.depth, deadline=deadline)
+            if best is None or evi > best[0]:
+                best = (evi, action)
+        if best is None or best[0] <= 0.0:
+            return None
+        evi, action = best
+        return ActionDecision(
+            kind=action,
+            rule_id="MIND-LOOKAHEAD",
+            priority=self.priority,
+            payload={
+                "evi": evi,
+                "depth": self.depth,
+                "posterior": (ctx.working_memory.get("posteriors") or {}).get(ctx.topic, 0.5),
+            },
+            reason=f"lookahead depth={self.depth}, EVI={evi:.3f}",
+        )
+    def _evi(self, action: ActionKind, ctx: PolicyContext, *, depth: int, deadline: float) -> float:
+        """Recursive expected value-of-information."""
+        if time.perf_counter() >= deadline:
+            return 0.0
+        outcome = self.world_model.predict(action, ctx)
+        if depth <= 0:
+            return outcome.posterior * outcome.confidence
+        # Discount future-step EVI by 0.7 — bog-standard horizon discount.
+        gamma = 0.7
+        next_steps = max(
+            (
+                self._evi(a, ctx, depth=depth - 1, deadline=deadline)
+                for a in self.candidates
+                if a is not action  # don't loop
+            ),
+            default=0.0,
+        )
+        return outcome.posterior * outcome.confidence + gamma * next_steps
+def update_world_model_from_resolution(
+    world_model: WorldModel,
+    *,
+    action: ActionKind,
+    ctx: PolicyContext,
+    oracle_outcome: float,
+) -> None:
+    """Wire helper — called when an oracle resolves a claim that came
+    from a deliberator-dispatched action."""
+    world_model.update_with_outcome(action, ctx, oracle_outcome)