hypermind 0.15.0__tar.gz → 0.17.0__tar.gz

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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypermind"
-version = "0.15.0"
+version = "0.17.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.17.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.17.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.17.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.17.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.17.0}/src/hypermind/orgs/sim.py

@@ -19,11 +19,16 @@ live model or server.
 
 from __future__ import annotations
 
+import asyncio
 import inspect
+from collections import deque
 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
@@ -111,6 +116,7 @@ class OrgSim:
         interventions: list[Any] | None = None,
         context_builder: Any = None,
         on_event: Callable[[dict[str, Any]], Any] | None = None,
+        max_concurrency: int = 16,
         members: int | None = None,
     ) -> None:
         self.model = model.scaled(members) if members is not None else model
@@ -149,6 +155,14 @@ 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
+        self._max_concurrency = max(1, max_concurrency)
+        # Scale: a bounded window of recent findings (label, unit, conf, text)
+        # so peer-grounding is O(window), never a full scan of all claims.
+        self._recent_findings: deque[tuple[str, str, float, str]] = deque(maxlen=256)
+        self._member_by_kid: dict[bytes, Member] = {}  # O(1) resolve lookups
+        self._observe_top_k = 12  # deliberator: observe only the top-k peers
 
     async def _emit(self, kind: str, **data: Any) -> None:
         """Fire a structured event to the on_event sink (async or sync)."""
@@ -172,6 +186,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)
+
+        # Members answer the question concurrently (network-bound).
+        thoughts = await self._gather_think(self._members, question)
+        responses: list[dict[str, Any]] = [
+            {
+                "label": m.label,
+                "role": m.role,
+                "reputation": self._member_reputation(m),
+                "confidence": post.mean(),
+                "reasoning": reasoning,
+            }
+            for m, post, reasoning, _tools in thoughts
+        ]
+        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)
@@ -216,20 +281,22 @@ class OrgSim:
                 bearer_token=self.relata_token,
                 memory_factory=self._relata_memory_factory,
             )
-            memory.open()
-            agent.attach_memory(memory)
+            agent.attach_memory(memory)  # opened concurrently below
 
             allowed = self._grants.get(slot.label, frozenset())
             responder = self._build_member_responder(slot, allowed)
-            self._members.append(
-                Member(
-                    agent=agent,
-                    slot=slot,
-                    responder=responder,
-                    memory=memory,
-                    tools=allowed,
-                )
+            member = Member(
+                agent=agent,
+                slot=slot,
+                responder=responder,
+                memory=memory,
+                tools=allowed,
             )
+            self._members.append(member)
+            self._member_by_kid[member.kid] = member  # O(1) resolve lookups
+
+        # Open all private notebooks concurrently (network I/O), bounded.
+        await self._gather_io(m.memory.open for m in self._members if m.memory)
 
     def _build_member_responder(self, slot: Slot, allowed: frozenset[str]) -> Any:
         tool_objs = [build_tool(name, **self._tool_context) for name in sorted(allowed)]
@@ -249,15 +316,47 @@ class OrgSim:
         )
 
     async def _teardown(self) -> None:
+        # Close private notebooks concurrently (blocking I/O), agents sequentially
+        # (they share one in-process world; close mutates its registries).
+        await self._gather_io(m.memory.close for m in self._members if m.memory)
         for m in self._members:
-            if m.memory is not None:
-                m.memory.close()
             await m.agent.close()
         if self._backend is not None:
             self._backend.close()
 
     # ---- the loop ------------------------------------------------------
 
+    async def _gather_io(self, sync_calls) -> None:
+        """Run blocking I/O callables (Relata open/close) concurrently in a
+        thread pool, bounded — so spin-up/teardown of thousands of agents
+        doesn't serialise thousands of blocking HTTP round-trips."""
+        sem = asyncio.Semaphore(self._max_concurrency)
+
+        async def one(fn):
+            async with sem:
+                await asyncio.to_thread(fn)
+
+        await asyncio.gather(*(one(fn) for fn in sync_calls))
+
+    async def _gather_think(
+        self, members: list[Member], topic: str
+    ) -> list[tuple[Member, Uncertainty, str, list]]:
+        """Run every member's think() concurrently (bounded).
+
+        The per-member LLM calls are independent and network-bound, so this is
+        the big speed-up: a round's think phase costs ~max(latency) instead of
+        sum(latency). Results are returned in member order (gather is ordered),
+        so downstream publish/track logic stays deterministic.
+        """
+        sem = asyncio.Semaphore(self._max_concurrency)
+
+        async def one(m: Member) -> tuple[Member, Uncertainty, str, list]:
+            async with sem:
+                post, reasoning, tool_calls = await self._think(m, topic)
+            return m, post, reasoning, tool_calls
+
+        return list(await asyncio.gather(*(one(m) for m in members)))
+
     async def run(self, topic: str, *, rounds: int | None = None) -> OrgReport:
         """Run the loop.
 
@@ -297,21 +396,25 @@ class OrgSim:
         for r in range(rounds):
             await self._emit("round_start", round=r, members=len(self._members))
             posteriors: dict[str, float] = {}
-            for m in self._members:
-                post, _reasoning, _tools = await self._think(m, topic)
+            for m, post, _reasoning, _tools in await self._gather_think(self._members, topic):
                 posteriors[m.label] = post.mean()
                 m.agent.working_memory().setdefault("posteriors", {})[m.unit] = post.mean()
-            # Cross-pollinate: each member observes its peers' posteriors.
+            # Cross-pollinate: each member observes the TOP-K peers by reputation,
+            # not every peer — O(members·k) instead of O(members²), so this
+            # stays tractable at thousands of agents.
+            k = min(len(self._members) - 1, self._observe_top_k)
+            ranked = sorted(self._members, key=lambda p: self._member_reputation(p), reverse=True)[
+                : k + 1
+            ]
             for m in self._members:
-                for peer in self._members:
+                for peer in ranked:
                     if peer.label == m.label:
                         continue
-                    rep = self._member_reputation(peer)
                     delibs[m.label].observe(
                         {
                             "topic": m.unit,
                             "posterior": posteriors[peer.label],
-                            "reputation": rep,
+                            "reputation": self._member_reputation(peer),
                             "kid": peer.kid,
                         }
                     )
@@ -363,11 +466,12 @@ class OrgSim:
             if getattr(iv, "round", None) == r:
                 await iv.apply(self)
         await self._emit("round_start", round=r, members=len(self._members))
-        # 1+2+3: recall → think → publish.
+        # 1+2: recall → think, run concurrently across members (network-bound).
+        thoughts = await self._gather_think(self._members, topic)
+        # 3: publish — sequential (mutates shared ledger + tracking, deterministic).
         published: list[tuple[Member, bytes, Uncertainty]] = []
         posteriors: dict[str, float] = {}
-        for m in self._members:
-            post, reasoning, tool_calls = await self._think(m, topic)
+        for m, post, reasoning, tool_calls in thoughts:
             posteriors[m.label] = post.mean()
             floor = self.interaction.publish_floor(role=m.role, base_floor=dyn.publish_floor)
             floor = min(1.0, max(0.0, floor + m.floor_adj))
@@ -449,11 +553,12 @@ class OrgSim:
         return post, reasoning, tool_calls
 
     def _recent_peer_findings(self, m: Member, *, limit: int = 3) -> list[str]:
-        """Top peer findings on the shared ledger — same unit first, by
-        confidence — so reasoning is grounded in what others have claimed."""
-        peers = [c for c in self._claims.values() if c.label != m.label and c.finding]
-        peers.sort(key=lambda c: (c.unit == m.unit, c.confidence), reverse=True)
-        return [f"{c.label}: {c.finding}" for c in peers[:limit]]
+        """Top peer findings from a **bounded window** of recent claims — same
+        unit first, by confidence. O(window), never a full scan of all claims,
+        so this stays flat as the ledger grows into the millions."""
+        peers = [f for f in self._recent_findings if f[0] != m.label]
+        peers.sort(key=lambda f: (f[1] == m.unit, f[2]), reverse=True)
+        return [f"{label}: {text}" for label, _unit, _conf, text in peers[:limit]]
 
     async def _publish(
         self,
@@ -488,6 +593,8 @@ class OrgSim:
             finding=reasoning,
             tool_calls=tool_calls,
         )
+        if reasoning:
+            self._recent_findings.append((m.label, m.unit, post.mean(), reasoning))
         if tool_calls:
             await self._emit(
                 "tool_call",
@@ -568,8 +675,8 @@ class OrgSim:
                 if info is not None:
                     info.outcome = outcome
                 await self._emit("resolve", by=rec.member_label, unit=unit, outcome=outcome)
-                # Evolve signal: publisher earns/loses floor headroom.
-                pub = next((m for m in self._members if m.kid == rec.member_kid), None)
+                # Evolve signal: publisher earns/loses floor headroom (O(1) lookup).
+                pub = self._member_by_kid.get(rec.member_kid)
                 if pub is not None:
                     pub.floor_adj += -0.03 if outcome else 0.05
 
@@ -599,10 +706,14 @@ class OrgSim:
 
     def _build_report(self, topic: str, rounds: int) -> OrgReport:
         world = self._members[0].agent._world if self._members else None
+        # Index claims by author once (O(claims)) instead of scanning per member.
+        by_label: dict[str, list[_ClaimInfo]] = {}
+        for c in self._claims.values():
+            by_label.setdefault(c.label, []).append(c)
         standings: list[MemberStanding] = []
         for m in self._members:
             score = world.reputation.snapshot(m.kid, m.unit).score if world else 0.0
-            authored = [c for c in self._claims.values() if c.label == m.label]
+            authored = by_label.get(m.label, [])
             standings.append(
                 MemberStanding(
                     label=m.label,

hypermind-0.17.0/tests/orgs/test_concurrency.py

@@ -0,0 +1,101 @@
+"""Concurrent think phase — parallel LLM calls, bounded, order-preserving."""
+
+from __future__ import annotations
+
+import asyncio
+
+import pytest
+from _fakes import FakeMemory, FakeStore, client_factory
+
+from hypermind.orgs import DynamicsConfig, OrgModel, OrgSim, Seat, Unit
+from hypermind.responders.base import confidence_to_uncertainty
+
+
+def _model(members=12) -> OrgModel:
+    base = OrgModel(
+        name="c",
+        namespace="c",
+        units=(
+            Unit(
+                "a",
+                seats=(
+                    Seat("O", role="oracle", authority=0.9),
+                    Seat("S", role="scout", authority=0.5, headcount=3),
+                ),
+            ),
+        ),
+        dynamics=DynamicsConfig(rounds=1),
+    )
+    return base.scaled(members)
+
+
+def _make(responder_factory, **kw) -> OrgSim:
+    return OrgSim(
+        _model(),
+        relata_url="http://fake",
+        responder_factory=responder_factory,
+        relata_client_factory=client_factory(FakeStore()),
+        relata_memory_factory=FakeMemory,
+        **kw,
+    )
+
+
+@pytest.mark.asyncio
+async def test_think_phase_runs_concurrently():
+    # Track how many responder calls are in-flight at once.
+    state = {"live": 0, "peak": 0}
+
+    def factory(slot, tools):
+        async def _resp(kid, query):
+            state["live"] += 1
+            state["peak"] = max(state["peak"], state["live"])
+            await asyncio.sleep(0.02)  # simulate network latency
+            state["live"] -= 1
+            return confidence_to_uncertainty(0.8, effective_n=10.0)
+
+        return _resp
+
+    await _make(factory).simulate("t", rounds=1)
+    # With 12 members and a sequential loop, peak would be 1. Concurrency lifts it.
+    assert state["peak"] > 1
+
+
+@pytest.mark.asyncio
+async def test_concurrency_cap_is_respected():
+    state = {"live": 0, "peak": 0}
+
+    def factory(slot, tools):
+        async def _resp(kid, query):
+            state["live"] += 1
+            state["peak"] = max(state["peak"], state["live"])
+            await asyncio.sleep(0.02)
+            state["live"] -= 1
+            return confidence_to_uncertainty(0.8, effective_n=10.0)
+
+        return _resp
+
+    await _make(factory, max_concurrency=3).simulate("t", rounds=1)
+    assert state["peak"] <= 3  # never exceeds the cap
+
+
+@pytest.mark.asyncio
+async def test_results_stay_deterministic_and_ordered():
+    # Confidence keyed by member label; concurrency must not scramble attribution.
+    order: list[str] = []
+
+    def factory(slot, tools):
+        async def _resp(kid, query):
+            # Finish out of submission order to stress ordering.
+            await asyncio.sleep(0.01 if slot.seat.role == "scout" else 0.03)
+            return confidence_to_uncertainty(
+                0.9 if slot.seat.role == "oracle" else 0.6, effective_n=10.0
+            )
+
+        return _resp
+
+    report = await _make(factory).simulate("t", rounds=1)
+    # Oracle (0.9) outranks scouts (0.6) — attribution preserved despite races.
+    top = report.standings[0]
+    assert report.summary()["claims"] > 0
+    assert all(0.0 <= s.reputation <= 1.0 for s in report.standings)
+    assert top.reputation >= min(s.reputation for s in report.standings)

hypermind-0.17.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"