hypermind 0.11.0__py3-none-any.whl

hypermind/deliberation.py

@@ -0,0 +1,355 @@
+"""Multi-cycle deliberation for consult panels.
+
+Single-shot LLM panels cannot revise on disagreement. The
+:func:`run_deliberation` loop runs the panel multiple times, surfacing
+each round's anonymised reasoning summaries back to every member as
+context for the next round, so the panel can refine, qualify, or
+rebut its earlier answers.
+
+Convergence:
+    Stop early when ``|disagreement_t - disagreement_{t-1}| < convergence_threshold``
+    OR when ``max_rounds`` is reached, whichever comes first.
+
+Backward-compat:
+    With ``max_rounds=1`` (the v0.5 default), this module is a no-op
+    pass-through to the existing single-shot behaviour. Existing
+    callers see no behavioural change.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from hypermind.consult import (
+    ArgumentEdge,
+    PanelMember,
+    aggregate_panel,
+)
+from hypermind.responders.base import unpack_responder_result
+from hypermind.uncertainty import Uncertainty
+
+if TYPE_CHECKING:
+    pass
+
+
+# ---------------------------------------------------------------------------
+# Round + result records
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class DeliberationRound:
+    """One round of the deliberation loop."""
+
+    round_index: int  # 0-based
+    panel: list[PanelMember]
+    aggregated: Uncertainty
+    disagreement: float
+    elapsed_ms: float
+    revision_edges: list[ArgumentEdge] = field(default_factory=list)
+
+
+@dataclass
+class DeliberationResult:
+    """Outcome of a multi-round deliberation.
+
+    ``rounds[-1]`` is always the final round whose ``aggregated`` and
+    ``panel`` populate the parent :class:`ConsultResult`.
+    """
+
+    rounds: list[DeliberationRound]
+    final_posterior: Uncertainty
+    final_disagreement: float
+    converged: bool
+    converged_reason: str
+
+    @property
+    def n_rounds(self) -> int:
+        return len(self.rounds)
+
+    @property
+    def final_panel(self) -> list[PanelMember]:
+        return self.rounds[-1].panel if self.rounds else []
+
+    def all_revision_edges(self) -> list[ArgumentEdge]:
+        out: list[ArgumentEdge] = []
+        for r in self.rounds:
+            out.extend(r.revision_edges)
+        return out
+
+
+# ---------------------------------------------------------------------------
+# Anonymised reasoning summary — what later rounds see
+# ---------------------------------------------------------------------------
+
+#: Soft cap on how many bytes of context each later round receives.
+#: Large summaries blow the token budget; we cap at ~3000 chars.
+MAX_DELIBERATION_CONTEXT_CHARS = 3000
+
+#: How much of each panel member's reasoning to include in the summary.
+MAX_REASONING_PER_MEMBER_CHARS = 240
+
+
+def _build_deliberation_context(
+    round_index: int,
+    panel: list[PanelMember],
+    disagreement: float,
+) -> str:
+    """Compose the round-N context sent to all members for round N+1.
+
+    Only ``StructuredResponse.reasoning`` is surfaced; agent kids are
+    anonymised to ``A1, A2, …`` so re-elicitation can't leak identity.
+    """
+    if not panel:
+        return ""
+
+    posteriors = [m.posterior.mean() for m in panel]
+    avg_post = sum(posteriors) / len(posteriors)
+
+    lines = [
+        f"--- Round {round_index} panel summary ---",
+        f"Aggregate posterior so far: {avg_post:.0%}.",
+        f"Panel disagreement (Jensen-Shannon): {disagreement:.3f} "
+        f"({'consensus' if disagreement < 0.10 else 'divided' if disagreement > 0.30 else 'mixed'}).",
+        "",
+        "Per-member reasoning (anonymised; revisit your answer in light of these):",
+    ]
+
+    used = sum(len(s) for s in lines)
+    for i, m in enumerate(panel, start=1):
+        if used >= MAX_DELIBERATION_CONTEXT_CHARS:
+            break
+        reasoning = ""
+        if m.structured is not None:
+            reasoning = (m.structured.reasoning or "").strip()
+        if not reasoning:
+            reasoning = f"(confidence={m.posterior.mean():.2f}; no reasoning recorded)"
+        if len(reasoning) > MAX_REASONING_PER_MEMBER_CHARS:
+            reasoning = reasoning[:MAX_REASONING_PER_MEMBER_CHARS].rstrip() + "…"
+        line = f"  · A{i} (confidence={m.posterior.mean():.2f}): {reasoning}"
+        lines.append(line)
+        used += len(line)
+
+    lines.append("")
+    lines.append(
+        "Now answer the original question again. You may keep, qualify, or "
+        "rebut your earlier answer. Be specific about what changed (or didn't) "
+        "given the panel summary."
+    )
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Revision edges — Toulmin/IBIS labels for round-over-round changes
+# ---------------------------------------------------------------------------
+
+#: How much the mean must shift to count as "qualified" vs "rebuts".
+QUALIFY_THRESHOLD = 0.10
+REBUT_THRESHOLD = 0.30
+
+
+def _classify_revision(prev_mean: float, new_mean: float) -> str:
+    """Return one of: ``"supports"``, ``"qualifies"``, ``"rebuts"``."""
+    delta = abs(new_mean - prev_mean)
+    if delta < QUALIFY_THRESHOLD:
+        return "supports"
+    # Direction flip across 0.5 → rebuts; same-side shift → qualifies
+    if (prev_mean - 0.5) * (new_mean - 0.5) < 0 or delta >= REBUT_THRESHOLD:
+        return "rebuts"
+    return "qualifies"
+
+
+def _build_revision_edges(
+    prev_panel: list[PanelMember],
+    new_panel: list[PanelMember],
+) -> list[ArgumentEdge]:
+    """Build edges from each agent's prev posterior to its new posterior."""
+    if not prev_panel or not new_panel:
+        return []
+    prev_by_kid: dict[bytes, PanelMember] = {m.agent_id: m for m in prev_panel}
+    edges: list[ArgumentEdge] = []
+    for new_m in new_panel:
+        prev_m = prev_by_kid.get(new_m.agent_id)
+        if prev_m is None:
+            continue
+        kind = _classify_revision(prev_m.posterior.mean(), new_m.posterior.mean())
+        edges.append(
+            ArgumentEdge(
+                src_kid=new_m.agent_id,
+                dst_kid=new_m.agent_id,
+                edge_type=kind,
+            )
+        )
+    return edges
+
+
+# ---------------------------------------------------------------------------
+# The loop
+# ---------------------------------------------------------------------------
+
+
+async def _elicit_round(
+    chosen: list[bytes],
+    contextualised_query: str,
+    responder: Callable[[bytes, str], Awaitable[Any]] | None,
+    default_posterior_for: Callable[[bytes], Uncertainty],
+    rep_for: Callable[[bytes], float],
+    timeout_s: float,
+    route_reason: str,
+    on_responder_error: Callable[[bytes, BaseException], None] | None = None,
+) -> list[PanelMember]:
+    """Dispatch one elicitation round and return the surviving panel members."""
+
+    async def _ask(kid: bytes) -> Any:
+        if responder is not None:
+            return await responder(kid, contextualised_query)
+        return default_posterior_for(rep_for(kid))
+
+    results = await asyncio.wait_for(
+        asyncio.gather(*(_ask(c) for c in chosen), return_exceptions=True),
+        timeout=timeout_s,
+    )
+
+    panel: list[PanelMember] = []
+    for c, r in zip(chosen, results, strict=True):
+        if isinstance(r, BaseException):
+            if on_responder_error is not None:
+                try:
+                    on_responder_error(c, r)
+                except Exception:
+                    pass
+            continue
+        try:
+            posterior, structured = unpack_responder_result(r)
+        except TypeError:
+            continue
+        panel.append(
+            PanelMember(
+                agent_id=c,
+                weight=rep_for(c),
+                posterior=posterior,
+                route_reason=route_reason,
+                structured=structured,
+            )
+        )
+    return panel
+
+
+async def run_deliberation(
+    *,
+    chosen: list[bytes],
+    query: str,
+    responder: Callable[[bytes, str], Awaitable[Any]] | None,
+    default_posterior_for: Callable[[bytes], Uncertainty],
+    rep_for: Callable[[bytes], float],
+    max_rounds: int,
+    convergence_threshold: float,
+    timeout_per_round_s: float,
+    route_reason: str,
+    on_responder_error: Callable[[bytes, BaseException], None] | None = None,
+) -> DeliberationResult:
+    """Run up to ``max_rounds`` of elicitation with anonymised feedback.
+
+    Round 0 elicits cold (just the original ``query``). Round k>0 prefixes
+    the query with anonymised reasoning summaries from round k-1. Stops
+    early when ``|Δ disagreement| < convergence_threshold``.
+    """
+    if max_rounds < 1:
+        raise ValueError("max_rounds must be >= 1")
+
+    rounds: list[DeliberationRound] = []
+    prev_disagreement: float | None = None
+    converged = False
+    converged_reason = "max_rounds_reached"
+
+    contextualised_query = query
+
+    for round_idx in range(max_rounds):
+        t0 = time.perf_counter()
+
+        panel = await _elicit_round(
+            chosen=chosen,
+            contextualised_query=contextualised_query,
+            responder=responder,
+            default_posterior_for=default_posterior_for,
+            rep_for=rep_for,
+            timeout_s=timeout_per_round_s,
+            route_reason=route_reason,
+            on_responder_error=on_responder_error,
+        )
+
+        if not panel:
+            converged = True
+            converged_reason = "no_panel_responses"
+            break
+
+        aggregated, disagreement = aggregate_panel(panel)
+        elapsed_ms = (time.perf_counter() - t0) * 1000.0
+
+        # Build revision edges by comparing to previous round (if any).
+        revision_edges: list[ArgumentEdge] = []
+        if rounds:
+            revision_edges = _build_revision_edges(rounds[-1].panel, panel)
+
+        rounds.append(
+            DeliberationRound(
+                round_index=round_idx,
+                panel=panel,
+                aggregated=aggregated,
+                disagreement=disagreement,
+                elapsed_ms=elapsed_ms,
+                revision_edges=revision_edges,
+            )
+        )
+
+        # Check convergence
+        if prev_disagreement is not None:
+            delta = abs(disagreement - prev_disagreement)
+            if delta < convergence_threshold:
+                converged = True
+                converged_reason = "disagreement_stable"
+                break
+        prev_disagreement = disagreement
+
+        # Build context for next round (only if we'll do another)
+        if round_idx + 1 < max_rounds:
+            ctx = _build_deliberation_context(
+                round_index=round_idx,
+                panel=panel,
+                disagreement=disagreement,
+            )
+            contextualised_query = f"{ctx}\n\n--- Original question ---\n{query}"
+
+    if not rounds:
+        # Shouldn't happen unless every responder errored on round 0.
+        # Caller is responsible for handling empty panel; we surface it.
+        return DeliberationResult(
+            rounds=[],
+            final_posterior=Uncertainty.beta(1.0, 1.0),
+            final_disagreement=0.0,
+            converged=True,
+            converged_reason="no_panel_responses",
+        )
+
+    return DeliberationResult(
+        rounds=rounds,
+        final_posterior=rounds[-1].aggregated,
+        final_disagreement=rounds[-1].disagreement,
+        converged=converged,
+        converged_reason=converged_reason,
+    )
+
+
+__all__ = [
+    "MAX_DELIBERATION_CONTEXT_CHARS",
+    "MAX_REASONING_PER_MEMBER_CHARS",
+    "QUALIFY_THRESHOLD",
+    "REBUT_THRESHOLD",
+    "DeliberationResult",
+    "DeliberationRound",
+    "run_deliberation",
+]

hypermind/did_web.py

@@ -0,0 +1,256 @@
+"""DID:web rendezvous for HyperMind namespaces (spec §24.6).
+
+Every namespace MUST publish a DID Document at::
+
+    did:web:<host>:hm:<namespace_id_hex>
+
+resolved per W3C DID Core. The document carries:
+
+* ``id`` — the DID URI itself
+* ``verificationMethod`` — at least one entry binding the namespace
+  ``root_pubkey`` (the FROST group public key from §24.3)
+* ``service[]`` — gossip endpoint advertisements for the namespace
+* ``proof`` — VC-Data-Integrity proof signed by the namespace root key
+
+This module supplies the format, builder, and resolver. Real HTTP
+fetching is reserved for v1.0; the :class:`DidWebResolver` accepts an
+``OfflineCache`` shim so unit tests do not perform live network calls.
+
+Document encoding: spec §24.6 references W3C VC-Data-Integrity, which
+is defined over JSON-LD. This implementation uses **canonical JSON
+sorted-keys** (RFC 8785-style) — the §24 OPEN GAP on resolution policy
+covers this; we flag the choice in :data:`DOC_ENCODING_NOTE`.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import asdict, dataclass, field
+
+from hypermind.crypto.namespace_root import NamespaceRoot
+
+DOC_ENCODING_NOTE = (
+    "did:web Document is serialised as canonical JSON sorted-keys per RFC 8785 "
+    "(spec §24.6 leaves the precise canonicalisation form open for v1.0 errata). "
+    "FROST proof is computed over the document with `proof.signatureValue` zeroed."
+)
+
+_DID_RE = re.compile(r"^did:web:([A-Za-z0-9._-]+):hm:([0-9a-f]{32,64})$")
+
+
+def format_did(host: str, ns_id: bytes) -> str:
+    """Format a HyperMind DID:web URI.
+
+    ``host`` is the operator-chosen DNS name; ``ns_id`` is the 16-byte
+    namespace UUIDv7 (or longer if a future profile uses 32 bytes).
+    """
+    if not host or not re.match(r"^[A-Za-z0-9._-]+$", host):
+        raise ValueError(f"invalid host {host!r}")
+    if not isinstance(ns_id, (bytes, bytearray)) or len(ns_id) not in (16, 32):
+        raise ValueError("ns_id must be 16 or 32 bytes")
+    return f"did:web:{host}:hm:{ns_id.hex()}"
+
+
+def parse_did(did: str) -> tuple[str, bytes]:
+    """Parse a HyperMind DID:web URI back into (host, ns_id)."""
+    m = _DID_RE.match(did)
+    if not m:
+        raise ValueError(f"not a HyperMind DID:web URI: {did!r}")
+    host = m.group(1)
+    hex_ns = m.group(2)
+    if len(hex_ns) not in (32, 64):  # 16 or 32 bytes hex
+        raise ValueError(f"namespace_id hex must be 32 or 64 chars, got {len(hex_ns)}")
+    return host, bytes.fromhex(hex_ns)
+
+
+@dataclass
+class VerificationMethod:
+    id: str
+    type: str
+    controller: str
+    publicKeyMultibase: str
+
+
+@dataclass
+class ServiceEntry:
+    id: str
+    type: str
+    serviceEndpoint: str
+
+
+@dataclass
+class Proof:
+    type: str = "FrostEd25519Signature2025"
+    proofPurpose: str = "assertionMethod"
+    verificationMethod: str = ""
+    signatureValue: str = ""
+
+
+@dataclass
+class DidDocument:
+    id: str
+    verificationMethod: list[VerificationMethod] = field(default_factory=list)
+    service: list[ServiceEntry] = field(default_factory=list)
+    proof: Proof = field(default_factory=Proof)
+
+    @classmethod
+    def build(
+        cls,
+        ns: NamespaceRoot,
+        host: str,
+        gossip_endpoints: list[str],
+        ns_id: bytes,
+    ) -> DidDocument:
+        """Build + sign a DID Document for the given namespace.
+
+        ``gossip_endpoints`` is a list of HyperMind gossip-bus URLs (TLS
+        endpoints from §22). Each becomes a `service` entry with
+        ``type: "HyperMindGossip"``.
+        """
+        did = format_did(host, ns_id)
+        # Multibase prefix `z` = base58-btc; we use base16 (`f`) + lowercase
+        # hex since libsodium ed25519 publickey is fixed-length.
+        pk_multibase = "f" + ns.group_pubkey.hex()
+        vm = VerificationMethod(
+            id=f"{did}#root",
+            type="Ed25519VerificationKey2020",
+            controller=did,
+            publicKeyMultibase=pk_multibase,
+        )
+        services = [
+            ServiceEntry(
+                id=f"{did}#gossip-{i}",
+                type="HyperMindGossip",
+                serviceEndpoint=ep,
+            )
+            for i, ep in enumerate(gossip_endpoints)
+        ]
+        doc = cls(
+            id=did,
+            verificationMethod=[vm],
+            service=services,
+            proof=Proof(verificationMethod=f"{did}#root"),
+        )
+        # Sign with FROST quorum over the canonical preimage (proof.sigValue zeroed).
+        preimage = doc._signing_preimage()
+        signer_subset = list(range(1, ns.k + 1))
+        sig = ns.sign(preimage, signer_subset)
+        doc.proof.signatureValue = sig.hex()
+        return doc
+
+    def _signing_preimage(self) -> bytes:
+        """Canonical JSON of the document with `proof.signatureValue` blank.
+
+        Per W3C VC-Data-Integrity, the proof value field is excluded from
+        the signed preimage. We zero it (empty string) and emit the
+        sorted-keys JSON form.
+        """
+        clone = DidDocument(
+            id=self.id,
+            verificationMethod=[VerificationMethod(**asdict(v)) for v in self.verificationMethod],
+            service=[ServiceEntry(**asdict(s)) for s in self.service],
+            proof=Proof(
+                type=self.proof.type,
+                proofPurpose=self.proof.proofPurpose,
+                verificationMethod=self.proof.verificationMethod,
+                signatureValue="",
+            ),
+        )
+        return json.dumps(clone._to_dict(), sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+    def _to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "verificationMethod": [asdict(v) for v in self.verificationMethod],
+            "service": [asdict(s) for s in self.service],
+            "proof": asdict(self.proof),
+        }
+
+    def serialize(self) -> bytes:
+        """Canonical JSON sorted-keys, UTF-8 — what the resolver fetches."""
+        return json.dumps(self._to_dict(), sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+    @classmethod
+    def deserialize(cls, raw: bytes) -> DidDocument:
+        data = json.loads(raw.decode("utf-8"))
+        return cls(
+            id=data["id"],
+            verificationMethod=[
+                VerificationMethod(**v) for v in data.get("verificationMethod", [])
+            ],
+            service=[ServiceEntry(**s) for s in data.get("service", [])],
+            proof=Proof(**data.get("proof", {})),
+        )
+
+
+def verify(doc_bytes: bytes, ns_root_pub: bytes) -> bool:
+    """Verify a serialised DID Document's FROST proof against ``ns_root_pub``.
+
+    Returns ``True`` iff the proof signature validates under the FROST
+    group public key declared in the matching ``NAMESPACE_FOUNDING_ATTEST``.
+    """
+    from hypermind.crypto import frost
+
+    try:
+        doc = DidDocument.deserialize(doc_bytes)
+    except (json.JSONDecodeError, KeyError, TypeError):
+        return False
+    sig_hex = doc.proof.signatureValue
+    if not sig_hex:
+        return False
+    try:
+        sig = bytes.fromhex(sig_hex)
+    except ValueError:
+        return False
+    if len(sig) != 64:
+        return False
+    preimage = doc._signing_preimage()
+    R = sig[:32]
+    z = sig[32:]
+    try:
+        return frost.verify(ns_root_pub, preimage, R, z, commitments=None)
+    except Exception:
+        return False
+
+
+class DidWebResolver:
+    """Resolver for ``did:web:...`` URIs.
+
+    Production resolvers fetch the document over HTTPS. Unit tests pass
+    a preloaded ``cache`` so resolution is deterministic and offline.
+
+    Parameters
+    ----------
+    cache:
+        Optional ``dict[str, bytes]`` mapping DID URI → serialized
+        document bytes. When set, resolution is offline-only.
+    """
+
+    def __init__(self, cache: dict[str, bytes] | None = None) -> None:
+        self._cache: dict[str, bytes] = dict(cache) if cache else {}
+
+    def preload(self, did: str, doc_bytes: bytes) -> None:
+        """Add a document to the offline cache."""
+        self._cache[did] = doc_bytes
+
+    def resolve(self, did: str) -> DidDocument:
+        """Resolve a DID URI to a :class:`DidDocument`.
+
+        Raises ``KeyError`` if the document is not cached. Real HTTP
+        fetching is reserved for v1.0 (spec §24.9 OPEN GAP on resolution
+        policy).
+        """
+        # Validate the URI shape before lookup so malformed inputs fail fast.
+        parse_did(did)
+        if did not in self._cache:
+            raise KeyError(
+                f"DID:web document not in offline cache: {did}. "
+                "Live HTTP resolution is reserved for v1.0; preload via "
+                "DidWebResolver(cache={did: doc_bytes})."
+            )
+        return DidDocument.deserialize(self._cache[did])
+
+
+class OfflineCache(dict):
+    """Marker subclass of dict — explicit name for resolver cache."""