hypermind 0.15.0__tar.gz → 0.16.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypermind
-Version: 0.15.0
+Version: 0.16.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.15.0 → hypermind-0.16.0}/pyproject.toml

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

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

@@ -59,6 +59,7 @@ from hypermind.orgs.model import (
     Slot,
     Unit,
 )
+from hypermind.orgs.query import Answer, Contributor, aggregate_answer
 from hypermind.orgs.receipt import VerifyResult, build_receipt, verify_receipt
 from hypermind.orgs.report import MemberStanding, OrgReport
 from hypermind.orgs.sim import OrgSim
@@ -74,8 +75,10 @@ from hypermind.orgs.tools import (
 
 __all__ = [
     "Adversarial",
+    "Answer",
     "CallableGroundTruth",
     "ContextBuilder",
+    "Contributor",
     "Cooperative",
     "Crowd",
     "DynamicsConfig",
@@ -100,6 +103,7 @@ __all__ = [
     "Variant",
     "VariantResult",
     "VerifyResult",
+    "aggregate_answer",
     "build_deliberator",
     "build_receipt",
     "build_tool",

hypermind-0.16.0/src/hypermind/orgs/query.py

@@ -0,0 +1,74 @@
+"""Study → ask: query a swarm about what it learned.
+
+The transparent flow: give a topic and a question, the swarm **studies the
+topic automatically** (the research loop — accumulating private memory, shared
+claims, and reputation), then **answers the question from what it learned**,
+aggregating each member's memory-grounded response weighted by the standing it
+earned. The caller does not orchestrate phases — one call does it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Contributor:
+    label: str
+    role: str
+    reputation: float
+    confidence: float
+    reasoning: str
+
+
+@dataclass(frozen=True)
+class Answer:
+    question: str
+    confidence: float  # reputation-weighted swarm confidence, 0..1
+    stance: str  # "supports" | "opposes" | "uncertain"
+    reasoning: str  # the highest-standing contributor's rationale
+    contributors: list[Contributor] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    def print(self) -> None:
+        print(f"\nQ: {self.question}")
+        print(f"A: {self.stance.upper()} (confidence {self.confidence:.2f})")
+        if self.reasoning:
+            print(f"   {self.reasoning}")
+        if self.contributors:
+            print("   drew on:")
+            for c in self.contributors[:5]:
+                print(f"     · {c.label} (rep {c.reputation:.2f}, conf {c.confidence:.2f})")
+
+
+def aggregate_answer(question: str, responses: list[dict[str, Any]]) -> Answer:
+    """Reputation-weighted aggregation of member responses into one answer."""
+    contribs = [
+        Contributor(
+            label=r["label"],
+            role=r.get("role", "?"),
+            reputation=float(r.get("reputation", 0.5)),
+            confidence=float(r.get("confidence", 0.5)),
+            reasoning=r.get("reasoning", ""),
+        )
+        for r in responses
+    ]
+    contribs.sort(key=lambda c: c.reputation, reverse=True)
+
+    total_w = sum(c.reputation for c in contribs)
+    if total_w > 0:
+        weighted = sum(c.confidence * c.reputation for c in contribs) / total_w
+    else:
+        weighted = 0.5
+    stance = "supports" if weighted >= 0.6 else "opposes" if weighted <= 0.4 else "uncertain"
+    lead = next((c.reasoning for c in contribs if c.reasoning), "")
+    return Answer(
+        question=question,
+        confidence=weighted,
+        stance=stance,
+        reasoning=lead,
+        contributors=contribs,
+    )

{hypermind-0.15.0 → hypermind-0.16.0}/src/hypermind/orgs/sim.py

@@ -23,7 +23,10 @@ import inspect
 from collections.abc import Callable
 from dataclasses import dataclass, field
 from statistics import pvariance
-from typing import Any
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from hypermind.orgs.query import Answer
 
 from hypermind.agent import HyperMindAgent
 from hypermind.mind.memory_store import RelataMemoryStore
@@ -149,6 +152,8 @@ class OrgSim:
         self._context_builder = context_builder or default_context_builder
         self._on_event = on_event
         self._decisions: list[dict[str, Any]] = []  # deliberator-mode decision trace
+        self._studied: bool = False
+        self._study_topic: str | None = None
 
     async def _emit(self, kind: str, **data: Any) -> None:
         """Fire a structured event to the on_event sink (async or sync)."""
@@ -172,6 +177,57 @@ class OrgSim:
         async with self:
             return await self.run(topic, rounds=rounds)
 
+    # ---- study → ask ---------------------------------------------------
+
+    async def study(self, topic: str, *, rounds: int | None = None) -> OrgReport:
+        """Run the learning loop so the swarm accumulates memory + standing on
+        ``topic``. Must be called inside ``async with``. Marks the swarm studied."""
+        report = await self.run(topic, rounds=rounds)
+        self._studied = True
+        self._study_topic = topic
+        return report
+
+    async def ask(
+        self, question: str, *, topic: str | None = None, study_rounds: int | None = None
+    ) -> Answer:
+        """Answer ``question`` from what the swarm learned.
+
+        Transparent + automatic: if the swarm hasn't studied yet it studies
+        first (on ``topic`` or the question itself), then every member recalls
+        its learned memory, reasons on the question, and the responses are
+        aggregated weighted by the standing each member earned.
+        """
+        from hypermind.orgs.query import aggregate_answer
+
+        if not self._studied:
+            await self.study(topic or question, rounds=study_rounds)
+
+        responses: list[dict[str, Any]] = []
+        for m in self._members:
+            post, reasoning, _tools = await self._think(m, question)
+            responses.append(
+                {
+                    "label": m.label,
+                    "role": m.role,
+                    "reputation": self._member_reputation(m),
+                    "confidence": post.mean(),
+                    "reasoning": reasoning,
+                }
+            )
+        return aggregate_answer(question, responses)
+
+    async def inquire(
+        self,
+        topic: str,
+        question: str,
+        *,
+        study_rounds: int | None = None,
+    ) -> Answer:
+        """One call: spin up, study ``topic``, answer ``question``, tear down."""
+        async with self:
+            await self.study(topic, rounds=study_rounds)
+            return await self.ask(question)
+
     async def _spin_up(self) -> None:
         roster = self.model.roster()
         total = len(roster)

hypermind-0.16.0/tests/orgs/test_query.py

@@ -0,0 +1,171 @@
+"""Study → ask (#queryable-swarm): auto-study then answer from learned memory."""
+
+from __future__ import annotations
+
+import pytest
+from _fakes import FakeStore, client_factory
+
+from hypermind.orgs import (
+    Answer,
+    DynamicsConfig,
+    OrgModel,
+    OrgSim,
+    Seat,
+    Unit,
+    aggregate_answer,
+)
+from hypermind.responders.base import confidence_to_uncertainty
+
+
+# --- unit: aggregation ----------------------------------------------------
+def test_aggregate_is_reputation_weighted():
+    # High-rep agent says yes (0.9), low-rep says no (0.1) → weighted toward yes.
+    responses = [
+        {
+            "label": "a/O#1",
+            "role": "oracle",
+            "reputation": 0.95,
+            "confidence": 0.9,
+            "reasoning": "yes because Z",
+        },
+        {
+            "label": "a/S#1",
+            "role": "scout",
+            "reputation": 0.2,
+            "confidence": 0.1,
+            "reasoning": "no",
+        },
+    ]
+    ans = aggregate_answer("Will X work?", responses)
+    assert ans.stance == "supports"
+    assert ans.confidence > 0.6
+    # Lead reasoning comes from the highest-standing contributor.
+    assert ans.reasoning == "yes because Z"
+    assert ans.contributors[0].label == "a/O#1"
+
+
+def test_aggregate_opposes_and_uncertain_bands():
+    lo = aggregate_answer("q", [{"label": "x", "reputation": 1.0, "confidence": 0.1}])
+    assert lo.stance == "opposes"
+    mid = aggregate_answer("q", [{"label": "x", "reputation": 1.0, "confidence": 0.5}])
+    assert mid.stance == "uncertain"
+
+
+def test_aggregate_zero_weight_defaults_to_uncertain():
+    ans = aggregate_answer("q", [{"label": "x", "reputation": 0.0, "confidence": 0.9}])
+    assert ans.confidence == 0.5 and ans.stance == "uncertain"
+
+
+def test_answer_to_dict_and_print(capsys):
+    ans = aggregate_answer(
+        "q",
+        [{"label": "a", "role": "oracle", "reputation": 0.9, "confidence": 0.8, "reasoning": "R"}],
+    )
+    d = ans.to_dict()
+    assert d["question"] == "q" and d["contributors"][0]["label"] == "a"
+    ans.print()
+    out = capsys.readouterr().out
+    assert "Q: q" in out and "drew on" in out
+
+
+# --- end-to-end -----------------------------------------------------------
+def _model() -> OrgModel:
+    return OrgModel(
+        name="q",
+        namespace="q",
+        units=(
+            Unit(
+                "a",
+                seats=(
+                    Seat("O", role="oracle", authority=0.9),
+                    Seat("S", role="scout", authority=0.5, headcount=2),
+                ),
+            ),
+        ),
+        dynamics=DynamicsConfig(rounds=2),
+    )
+
+
+class _RecordingMemory:
+    """Records remembered content and returns it on recall (learned memory)."""
+
+    def __init__(self):
+        self.contents: list[str] = []
+
+    def add(self, content, *, confidence=1.0, memory_class="semantic"):
+        self.contents.append(content)
+        return f"m{len(self.contents)}"
+
+    def add_batch(self, items, *, session_id=None):
+        return [self.add(i) for i in items]
+
+    def search(self, q, *, top_k=5, as_of=None):
+        return [{"content": c, "score": 1.0} for c in self.contents[-top_k:]]
+
+    def justify(self, mid):
+        return {"memory_id": mid}
+
+    def close(self):
+        pass
+
+
+def _factory(slot, tools):
+    async def _resp(kid, query):
+        # Answer high; if the agent has learned notes in the prompt, even higher.
+        conf = 0.9 if "concluded in earlier rounds" in query else 0.8
+        return confidence_to_uncertainty(conf, effective_n=10.0)
+
+    return _resp
+
+
+def _sim():
+    return OrgSim(
+        _model(),
+        relata_url="http://fake",
+        responder_factory=_factory,
+        relata_client_factory=client_factory(FakeStore()),
+        relata_memory_factory=_RecordingMemory,
+    )
+
+
+@pytest.mark.asyncio
+async def test_inquire_one_call_studies_then_answers():
+    ans = await _sim().inquire(
+        topic="protein folding", question="Would method X help?", study_rounds=2
+    )
+    assert isinstance(ans, Answer)
+    assert ans.question == "Would method X help?"
+    assert 0.0 <= ans.confidence <= 1.0
+    assert ans.contributors  # every member contributed
+
+
+@pytest.mark.asyncio
+async def test_ask_auto_studies_on_first_call():
+    sim = _sim()
+    async with sim:
+        assert sim._studied is False
+        ans = await sim.ask("Does it hold?", topic="topic-Y", study_rounds=1)
+        assert sim._studied is True  # studied automatically
+        assert isinstance(ans, Answer)
+
+
+@pytest.mark.asyncio
+async def test_ask_answers_from_learned_memory():
+    # After studying, agents recall prior notes → their answer is grounded in them.
+    sim = _sim()
+    async with sim:
+        await sim.study("topic-Z", rounds=2)
+        ans = await sim.ask("Follow-up question?")
+        # Learned notes were recalled (confidence lifted to the grounded branch).
+        assert ans.contributors
+        assert max(c.confidence for c in ans.contributors) >= 0.9
+
+
+@pytest.mark.asyncio
+async def test_second_ask_reuses_study():
+    sim = _sim()
+    async with sim:
+        await sim.ask("Q1", topic="t", study_rounds=1)
+        studied_after_q1 = sim._studied
+        a2 = await sim.ask("Q2")  # no re-study
+        assert studied_after_q1 and a2.question == "Q2"