hypermind 0.13.0__tar.gz → 0.14.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypermind
-Version: 0.13.0
+Version: 0.14.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.13.0 → hypermind-0.14.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypermind"
-version = "0.13.0"
+version = "0.14.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.13.0 → hypermind-0.14.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.13.0"
+__version__ = "0.14.0"
 
 #: SLSA build-provenance level committed for every release artefact.
 #: Cosign keyless signing + slsa-github-generator + PEP 740 attestations

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

@@ -24,6 +24,12 @@ worked examples of the mapping.
 
 from __future__ import annotations
 
+from hypermind.orgs.experiment import (
+    Experiment,
+    ExperimentResult,
+    Variant,
+    VariantResult,
+)
 from hypermind.orgs.groundtruth import (
     CallableGroundTruth,
     GroundTruth,
@@ -37,6 +43,12 @@ from hypermind.orgs.interaction import (
     Interaction,
     get_interaction,
 )
+from hypermind.orgs.intervention import (
+    FlipPersona,
+    InjectEvent,
+    Intervention,
+    RemoveMember,
+)
 from hypermind.orgs.metrics import ScoreCard, compute_scorecard
 from hypermind.orgs.model import (
     DynamicsConfig,
@@ -62,18 +74,26 @@ __all__ = [
     "Cooperative",
     "Crowd",
     "DynamicsConfig",
+    "Experiment",
+    "ExperimentResult",
+    "FlipPersona",
     "GroundTruth",
+    "InjectEvent",
     "Interaction",
+    "Intervention",
     "LLMJudgeGroundTruth",
     "MemberStanding",
     "OrgModel",
     "OrgReport",
     "OrgSim",
+    "RemoveMember",
     "ScoreCard",
     "Seat",
     "Slot",
     "StaticGroundTruth",
     "Unit",
+    "Variant",
+    "VariantResult",
     "build_tool",
     "compute_scorecard",
     "declarative_grants",

hypermind-0.14.0/src/hypermind/orgs/experiment.py

@@ -0,0 +1,159 @@
+"""Experiment harness (#158) — sweeps, replicas, A/B, run diffing.
+
+Researchers need reproducibility and comparison, not one-shot demos. An
+``Experiment`` runs a base :class:`OrgModel` under several named **variants**
+(dynamics overrides, member count, structural transforms, or sim-kwarg
+overrides), N replicas each, and aggregates the per-run scorecards into
+mean±stdev per metric — with a ``diff`` to see what moved between variants.
+
+Pure orchestration over ``OrgSim`` + the scorecard (#151); with a deterministic
+(fake) responder the whole thing is unit-testable with no live LLM/Relata.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from dataclasses import dataclass, field, replace
+from statistics import mean, pstdev
+from typing import Any
+
+from hypermind.orgs.model import OrgModel
+from hypermind.orgs.sim import OrgSim
+
+# Scalar scorecard fields we aggregate (bool coerced to 0/1; None skipped).
+_SCALAR_METRICS = (
+    "rounds",
+    "converged",
+    "time_to_consensus",
+    "final_spread",
+    "unit_polarization",
+    "brier_mean",
+    "claims",
+    "disputes",
+    "citations",
+    "participation_rate",
+)
+
+
+@dataclass(frozen=True)
+class Variant:
+    """A named experimental condition applied to the base model + sim kwargs."""
+
+    name: str
+    dynamics: dict[str, Any] | None = None  # DynamicsConfig field overrides
+    members: int | None = None
+    model_transform: Callable[[OrgModel], OrgModel] | None = None
+    sim_overrides: dict[str, Any] = field(default_factory=dict)
+
+    def build_model(self, base: OrgModel) -> OrgModel:
+        model = self.model_transform(base) if self.model_transform else base
+        if self.dynamics:
+            model = replace(model, dynamics=replace(model.dynamics, **self.dynamics))
+        return model
+
+
+@dataclass(frozen=True)
+class VariantResult:
+    name: str
+    replicas: int
+    metrics: dict[str, tuple[float, float]]  # metric -> (mean, stdev)
+    raw: list[dict[str, Any]]  # per-replica scorecards
+
+    def value(self, metric: str) -> float | None:
+        m = self.metrics.get(metric)
+        return m[0] if m else None
+
+
+@dataclass(frozen=True)
+class ExperimentResult:
+    topic: str
+    variants: dict[str, VariantResult]
+
+    def diff(self, a: str, b: str) -> dict[str, float]:
+        """Metric deltas (variant ``b`` minus variant ``a``) for shared metrics."""
+        va, vb = self.variants[a], self.variants[b]
+        out: dict[str, float] = {}
+        for metric, (mean_b, _) in vb.metrics.items():
+            if metric in va.metrics:
+                out[metric] = mean_b - va.metrics[metric][0]
+        return out
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "topic": self.topic,
+            "variants": {
+                name: {"replicas": v.replicas, "metrics": v.metrics}
+                for name, v in self.variants.items()
+            },
+        }
+
+
+def _aggregate(scorecards: list[dict[str, Any]]) -> dict[str, tuple[float, float]]:
+    out: dict[str, tuple[float, float]] = {}
+    for metric in _SCALAR_METRICS:
+        vals: list[float] = []
+        for sc in scorecards:
+            v = sc.get(metric)
+            if v is None:
+                continue
+            vals.append(1.0 if v is True else 0.0 if v is False else float(v))
+        if vals:
+            out[metric] = (mean(vals), pstdev(vals) if len(vals) > 1 else 0.0)
+    return out
+
+
+class Experiment:
+    """Run a base model under several variants and compare the scorecards."""
+
+    def __init__(
+        self,
+        base_model: OrgModel,
+        *,
+        relata_url: str,
+        max_concurrency: int = 4,
+        **sim_kwargs: Any,
+    ) -> None:
+        self.base_model = base_model
+        self.relata_url = relata_url
+        self._sim_kwargs = sim_kwargs
+        self._variants: list[Variant] = []
+        self._sem = asyncio.Semaphore(max(1, max_concurrency))
+
+    def variant(self, name: str, **overrides: Any) -> Experiment:
+        """Register a variant. ``overrides`` may include ``dynamics``,
+        ``members``, ``model_transform``, ``sim_overrides``."""
+        if any(v.name == name for v in self._variants):
+            raise ValueError(f"duplicate variant name {name!r}")
+        self._variants.append(Variant(name=name, **overrides))
+        return self
+
+    async def _run_one(self, variant: Variant, topic: str, rounds: int | None) -> dict[str, Any]:
+        model = variant.build_model(self.base_model)
+        kwargs = {**self._sim_kwargs, **variant.sim_overrides}
+        if variant.members is not None:
+            kwargs["members"] = variant.members
+        async with self._sem:
+            sim = OrgSim(model, relata_url=self.relata_url, **kwargs)
+            report = await sim.simulate(topic, rounds=rounds)
+        return report.scorecard
+
+    async def run(
+        self, topic: str, *, replicas: int = 1, rounds: int | None = None
+    ) -> ExperimentResult:
+        if not self._variants:
+            raise ValueError("no variants registered; call .variant(...) first")
+        if replicas < 1:
+            raise ValueError(f"replicas must be >= 1, got {replicas}")
+        results: dict[str, VariantResult] = {}
+        for variant in self._variants:
+            scorecards = await asyncio.gather(
+                *(self._run_one(variant, topic, rounds) for _ in range(replicas))
+            )
+            results[variant.name] = VariantResult(
+                name=variant.name,
+                replicas=replicas,
+                metrics=_aggregate(list(scorecards)),
+                raw=list(scorecards),
+            )
+        return ExperimentResult(topic=topic, variants=results)

hypermind-0.14.0/src/hypermind/orgs/intervention.py

@@ -0,0 +1,72 @@
+"""Counterfactual interventions (#159) — perturb a run mid-flight.
+
+Controlled what-if is the point of a simulator: inject a shock, ablate an
+agent, or flip a persona at a chosen round, then compare the perturbed run to
+the baseline (pair two runs with the same seed via
+:class:`~hypermind.orgs.experiment.Experiment` and read ``diff``).
+
+An ``Intervention`` fires at the *start* of its ``round`` (before members
+think), so its effect propagates through that round's reasoning.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from hypermind.orgs.sim import OrgSim
+
+
+@runtime_checkable
+class Intervention(Protocol):
+    round: int
+
+    async def apply(self, sim: OrgSim) -> None: ...
+
+
+@dataclass
+class InjectEvent:
+    """A shock every member observes — written to each agent's memory so it
+    surfaces in the next round's recall and colours reasoning."""
+
+    round: int
+    text: str
+
+    async def apply(self, sim: OrgSim) -> None:
+        for m in sim._members:
+            await m.agent.remember(f"[EVENT] {self.text}", confidence=1.0)
+        sim._events.append({"round": self.round, "text": self.text})
+
+
+@dataclass
+class RemoveMember:
+    """Ablate a member (by label) from the simulation."""
+
+    round: int
+    label: str
+
+    async def apply(self, sim: OrgSim) -> None:
+        before = len(sim._members)
+        sim._members = [m for m in sim._members if m.label != self.label]
+        if len(sim._members) != before:
+            sim._events.append({"round": self.round, "removed": self.label})
+
+
+@dataclass
+class FlipPersona:
+    """Swap a member's responder mid-run (e.g. change its stance/model).
+
+    ``responder`` is any ``async (agent_kid, query) -> ResponderResult`` — build
+    it with a new system prompt/model, or inject a fake in tests.
+    """
+
+    round: int
+    label: str
+    responder: Any
+
+    async def apply(self, sim: OrgSim) -> None:
+        for m in sim._members:
+            if m.label == self.label:
+                m.responder = self.responder
+                sim._events.append({"round": self.round, "flipped": self.label})

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

@@ -40,6 +40,7 @@ class OrgReport:
     tool_grants: dict[str, list[str]]
     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
 
     # ---- derived views -------------------------------------------------
 

{hypermind-0.13.0 → hypermind-0.14.0}/src/hypermind/orgs/sim.py

@@ -105,6 +105,7 @@ class OrgSim:
         ground_truth: GroundTruth | Callable[[str, dict[str, Any]], Any] | None = None,
         relata_client_factory: Callable[[], tuple[Any, Any, Any]] | None = None,
         relata_memory_factory: Callable[[], Any] | None = None,
+        interventions: list[Any] | None = None,
         members: int | None = None,
     ) -> None:
         self.model = model.scaled(members) if members is not None else model
@@ -138,6 +139,8 @@ class OrgSim:
         self._grants: dict[str, frozenset[str]] = {}
         self._round_posteriors: list[dict[str, float]] = []  # per-round {label: mean}
         self._stop_reason: str = "fixed"
+        self._interventions = list(interventions or [])
+        self._events: list[dict[str, Any]] = []  # applied interventions log
 
     # ---- lifecycle -----------------------------------------------------
 
@@ -284,6 +287,10 @@ class OrgSim:
 
     async def _round(self, topic: str, r: int) -> None:
         dyn = self.model.dynamics
+        # 0: fire any interventions scheduled for this round, before members think.
+        for iv in self._interventions:
+            if getattr(iv, "round", None) == r:
+                await iv.apply(self)
         # 1+2+3: recall → think → publish.
         published: list[tuple[Member, bytes, Uncertainty]] = []
         posteriors: dict[str, float] = {}
@@ -519,4 +526,5 @@ class OrgSim:
             tool_grants={label: sorted(t) for label, t in self._grants.items()},
             scorecard=scorecard.to_dict(),
             stop_reason=self._stop_reason,
+            events=list(self._events),
         )

hypermind-0.14.0/tests/orgs/test_experiment.py

@@ -0,0 +1,138 @@
+"""Experiment harness (#158) — variants, replicas, aggregation, diff.
+
+Deterministic fake responder → replicas are identical (stdev 0), so A/B deltas
+are exact and testable with no live LLM/Relata.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+import pytest
+from _fakes import FakeMemory, FakeStore, client_factory
+
+from hypermind.orgs import DynamicsConfig, Experiment, OrgModel, Seat, Unit
+from hypermind.orgs.experiment import Variant, _aggregate
+from hypermind.responders.base import confidence_to_uncertainty
+
+
+def _base_model() -> OrgModel:
+    return OrgModel(
+        name="exp",
+        namespace="exp",
+        units=(
+            Unit(
+                "a",
+                seats=(
+                    Seat("O", role="oracle", authority=0.9),
+                    Seat("S", role="scout", authority=0.5, headcount=2),
+                ),
+            ),
+        ),
+        dynamics=DynamicsConfig(rounds=1),
+    )
+
+
+def _responder_factory(slot, tools):
+    # Oracle confident, scouts moderate → deterministic per role.
+    conf = {"oracle": 0.85, "scout": 0.6}.get(slot.seat.role, 0.6)
+
+    async def _resp(kid, query):
+        return confidence_to_uncertainty(conf, effective_n=10.0)
+
+    return _resp
+
+
+def _experiment() -> Experiment:
+    return Experiment(
+        _base_model(),
+        relata_url="http://fake",
+        responder_factory=_responder_factory,
+        relata_client_factory=client_factory(FakeStore()),
+        relata_memory_factory=FakeMemory,
+    )
+
+
+# --- unit: aggregation ----------------------------------------------------
+def test_aggregate_means_and_coerces_bools_and_skips_none():
+    scorecards = [
+        {"converged": True, "brier_mean": 0.2, "time_to_consensus": None, "claims": 4},
+        {"converged": False, "brier_mean": 0.4, "time_to_consensus": 1, "claims": 6},
+    ]
+    agg = _aggregate(scorecards)
+    assert agg["converged"][0] == 0.5  # True+False → 0.5
+    assert agg["brier_mean"][0] == pytest.approx(0.3)
+    assert agg["claims"] == (5.0, 1.0)  # mean 5, pstdev 1
+    assert agg["time_to_consensus"][0] == 1.0  # None skipped, only the 1 counts
+
+
+# --- end-to-end -----------------------------------------------------------
+@pytest.mark.asyncio
+async def test_replicas_are_deterministic_zero_stdev():
+    exp = _experiment().variant("base")
+    result = await exp.run("topic", replicas=3, rounds=1)
+    v = result.variants["base"]
+    assert v.replicas == 3
+    # Deterministic responder → every replica identical → stdev 0 everywhere.
+    assert all(std == 0.0 for _, std in v.metrics.values())
+
+
+@pytest.mark.asyncio
+async def test_ab_variant_diff_shows_metric_movement():
+    # Variant B resolves more claims (higher oracle_resolve_frac) than A.
+    exp = (
+        _experiment()
+        .variant("low_resolve", dynamics={"oracle_resolve_frac": 0.0})
+        .variant("high_resolve", dynamics={"oracle_resolve_frac": 1.0})
+    )
+    result = await exp.run("topic", replicas=1, rounds=1)
+    diff = result.diff("low_resolve", "high_resolve")
+    assert set(diff) & {"claims", "participation_rate", "final_spread"}
+    # Both variants ran and produced scorecards.
+    assert result.variants["low_resolve"].value("rounds") == 1.0
+
+
+@pytest.mark.asyncio
+async def test_model_transform_variant_adds_a_sceptic():
+    def add_sceptic(model: OrgModel) -> OrgModel:
+        unit = model.units[0]
+        new_unit = replace(unit, seats=(*unit.seats, Seat("Skeptic", role="sceptic")))
+        return replace(model, units=(new_unit,))
+
+    exp = _experiment().variant("no_sceptic").variant("with_sceptic", model_transform=add_sceptic)
+    result = await exp.run("topic", replicas=1, rounds=1)
+    assert "with_sceptic" in result.variants
+    d = result.to_dict()
+    assert d["topic"] == "topic" and set(d["variants"]) == {"no_sceptic", "with_sceptic"}
+
+
+@pytest.mark.asyncio
+async def test_members_override_scales_variant():
+    exp = _experiment().variant("big", members=6)
+    result = await exp.run("topic", replicas=1, rounds=1)
+    assert result.variants["big"].value("rounds") == 1.0
+
+
+# --- validation -----------------------------------------------------------
+def test_duplicate_variant_rejected():
+    exp = _experiment().variant("x")
+    with pytest.raises(ValueError, match="duplicate variant"):
+        exp.variant("x")
+
+
+@pytest.mark.asyncio
+async def test_run_without_variants_raises():
+    with pytest.raises(ValueError, match="no variants"):
+        await _experiment().run("t")
+
+
+@pytest.mark.asyncio
+async def test_run_rejects_zero_replicas():
+    with pytest.raises(ValueError, match="replicas must be"):
+        await _experiment().variant("x").run("t", replicas=0)
+
+
+def test_variant_build_model_applies_dynamics():
+    v = Variant("v", dynamics={"rounds": 9})
+    m = v.build_model(_base_model())
+    assert m.dynamics.rounds == 9

hypermind-0.14.0/tests/orgs/test_intervention.py

@@ -0,0 +1,126 @@
+"""Counterfactual interventions (#159) — inject / remove / flip mid-run."""
+
+from __future__ import annotations
+
+import pytest
+from _fakes import FakeMemory, FakeStore, client_factory
+
+from hypermind.orgs import (
+    DynamicsConfig,
+    FlipPersona,
+    InjectEvent,
+    Intervention,
+    OrgModel,
+    OrgSim,
+    RemoveMember,
+    Seat,
+    Unit,
+)
+from hypermind.responders.base import confidence_to_uncertainty
+
+
+class _RecordingMemory(FakeMemory):
+    """FakeMemory that keeps what was remembered, to observe InjectEvent."""
+
+    def __init__(self):
+        super().__init__()
+        self.contents: list[str] = []
+
+    def add(self, content, *, confidence=1.0, memory_class="semantic"):
+        self.contents.append(content)
+        return super().add(content, confidence=confidence, memory_class=memory_class)
+
+
+def _model(rounds=2) -> OrgModel:
+    return OrgModel(
+        name="iv",
+        namespace="iv",
+        units=(
+            Unit(
+                "a",
+                seats=(
+                    Seat("O", role="oracle", authority=0.9),
+                    Seat("S", role="scout", authority=0.5, headcount=2),
+                ),
+            ),
+        ),
+        dynamics=DynamicsConfig(rounds=rounds),
+    )
+
+
+def _responder_factory(slot, tools):
+    async def _resp(kid, query):
+        return confidence_to_uncertainty(0.8, effective_n=10.0)
+
+    return _resp
+
+
+def _sim(interventions, *, memory_factory=FakeMemory, model=None) -> OrgSim:
+    return OrgSim(
+        model or _model(),
+        relata_url="http://fake",
+        responder_factory=_responder_factory,
+        relata_client_factory=client_factory(FakeStore()),
+        relata_memory_factory=memory_factory,
+        interventions=interventions,
+    )
+
+
+def test_builtins_satisfy_protocol():
+    assert isinstance(InjectEvent(0, "x"), Intervention)
+    assert isinstance(RemoveMember(0, "a/O#1"), Intervention)
+    assert isinstance(FlipPersona(0, "a/O#1", None), Intervention)
+
+
+@pytest.mark.asyncio
+async def test_inject_event_is_remembered_by_all_members():
+    mem = _RecordingMemory()
+    sim = _sim([InjectEvent(round=1, text="new evidence: X collapsed")], memory_factory=lambda: mem)
+    report = await sim.simulate("t", rounds=2)
+    # Recorded on each member's memory (shared recording fake here).
+    assert any("[EVENT] new evidence: X collapsed" in c for c in mem.contents)
+    assert any(e.get("text", "").startswith("new evidence") for e in report.events)
+
+
+@pytest.mark.asyncio
+async def test_remove_member_ablates_from_standings():
+    sim = _sim([RemoveMember(round=0, label="a/S#1")])
+    report = await sim.simulate("t", rounds=1)
+    labels = {s.label for s in report.standings}
+    assert "a/S#1" not in labels  # ablated before it could act
+    assert any(e.get("removed") == "a/S#1" for e in report.events)
+
+
+@pytest.mark.asyncio
+async def test_remove_unknown_member_is_a_noop():
+    sim = _sim([RemoveMember(round=0, label="ghost")])
+    report = await sim.simulate("t", rounds=1)
+    assert report.events == []  # nothing removed → no event logged
+
+
+@pytest.mark.asyncio
+async def test_flip_persona_swaps_responder_midrun():
+    async def new_responder(kid, query):
+        return confidence_to_uncertainty(0.1, effective_n=10.0)
+
+    sim = _sim([FlipPersona(round=1, label="a/O#1", responder=new_responder)])
+    async with sim:
+        report = await sim.run("t", rounds=2)
+        target = next(m for m in sim._members if m.label == "a/O#1")
+        assert target.responder is new_responder
+    assert any(e.get("flipped") == "a/O#1" for e in report.events)
+
+
+@pytest.mark.asyncio
+async def test_no_interventions_leaves_events_empty():
+    report = await _sim([]).simulate("t", rounds=1)
+    assert report.events == []
+
+
+@pytest.mark.asyncio
+async def test_intervention_only_fires_on_its_round():
+    # Scheduled for round 5 but the run is 1 round → never fires.
+    sim = _sim([RemoveMember(round=5, label="a/S#1")])
+    report = await sim.simulate("t", rounds=1)
+    assert "a/S#1" in {s.label for s in report.standings}
+    assert report.events == []