hypermind 0.11.0__tar.gz → 0.13.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypermind
-Version: 0.11.0
+Version: 0.13.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
@@ -213,9 +213,33 @@ This is how humans work. We talk, we cite, we disagree, we build reputations, we
 
 ---
 
-## SimLab modes (the demo)
+## Simulate any network — `hypermind.orgs` (the engine)
 
-`hmctl simlab` ships 8 deliberation modes that exercise different protocol primitives:
+The SDK ships a **living-simulation engine**: spin up a network of LLM-backed agents with roles, per-agent models, and group-scoped native tools, then run a `research → publish → cite → dispute → resolve → learn → evolve` loop persisted to Relata. One general engine expresses many scenarios — a university researching a hard problem, a city at war, a foreign-policy cabinet, an internet crowd reacting to a what-if — via pluggable **interaction strategies** (`cooperative` / `adversarial` / `crowd`) and an override hook for custom phases.
+
+```python
+from hypermind.orgs import OrgSim
+from hypermind.orgs.templates import university   # or: city_at_war, un_security_council, ...
+
+model = university(members=24)                     # generic OrgModel, scaled to 24 people
+report = await OrgSim(model, relata_url="http://localhost:9090",
+                      llm="anthropic", llm_client=client).simulate(
+                          topic="What limits ab-initio protein folding?", rounds=6)
+report.print()        # reputation ranking · citation graph · dispute ledger · calibration
+```
+
+- **Generic core, template library.** `OrgModel` / `Unit` / `Seat` are org-agnostic; `hypermind.orgs.templates` ships ready presets (`university`, `hospital`, `city_at_war`, `foreign_policy_cabinet`, `un_security_council`, `internet_crowd`, `research_lab`) — pure convenience data the core never imports. Roll your own network from the primitives.
+- **Per-agent models.** Any seat can pin its own provider/model (`Seat("Professor", llm="anthropic", model="claude-opus-4-8")`), or hand `OrgSim` a router for random / cost-aware assignment.
+- **Native tools, group-scoped.** Tools (web search, retrieval, KB query, Relata research) are granted per unit/seat and enforced — an ungranted tool is *absent* from that agent's toolset. Grants can be declarative or randomised; register your own with `hypermind.orgs.register_tool(...)`.
+- **Relata end-to-end.** Organisation → tenant; member → private memory session (agent kid); claims / disputes / reputation → tenant-scoped ledger rows; chain of custody → the Merkle log. Restart replays the whole org.
+
+Worked example: [`examples/org_university.py`](examples/org_university.py). Discover all presets via `hypermind.orgs.templates.list_templates()`.
+
+---
+
+## SimLab modes (the demo UI)
+
+**SimLab is a demo app**, not the core — a Vue web UI (bundled under `hypermind.simlab`) that visualises the same SDK primitives the `hypermind.orgs` engine drives programmatically. Use `hypermind.orgs` to build simulations; use SimLab to *watch* one. `hmctl simlab` ships 8 deliberation modes that exercise different protocol primitives:
 
 | Mode | One-liner |
 |---|---|

{hypermind-0.11.0 → hypermind-0.13.0}/README.md

@@ -125,9 +125,33 @@ This is how humans work. We talk, we cite, we disagree, we build reputations, we
 
 ---
 
-## SimLab modes (the demo)
+## Simulate any network — `hypermind.orgs` (the engine)
 
-`hmctl simlab` ships 8 deliberation modes that exercise different protocol primitives:
+The SDK ships a **living-simulation engine**: spin up a network of LLM-backed agents with roles, per-agent models, and group-scoped native tools, then run a `research → publish → cite → dispute → resolve → learn → evolve` loop persisted to Relata. One general engine expresses many scenarios — a university researching a hard problem, a city at war, a foreign-policy cabinet, an internet crowd reacting to a what-if — via pluggable **interaction strategies** (`cooperative` / `adversarial` / `crowd`) and an override hook for custom phases.
+
+```python
+from hypermind.orgs import OrgSim
+from hypermind.orgs.templates import university   # or: city_at_war, un_security_council, ...
+
+model = university(members=24)                     # generic OrgModel, scaled to 24 people
+report = await OrgSim(model, relata_url="http://localhost:9090",
+                      llm="anthropic", llm_client=client).simulate(
+                          topic="What limits ab-initio protein folding?", rounds=6)
+report.print()        # reputation ranking · citation graph · dispute ledger · calibration
+```
+
+- **Generic core, template library.** `OrgModel` / `Unit` / `Seat` are org-agnostic; `hypermind.orgs.templates` ships ready presets (`university`, `hospital`, `city_at_war`, `foreign_policy_cabinet`, `un_security_council`, `internet_crowd`, `research_lab`) — pure convenience data the core never imports. Roll your own network from the primitives.
+- **Per-agent models.** Any seat can pin its own provider/model (`Seat("Professor", llm="anthropic", model="claude-opus-4-8")`), or hand `OrgSim` a router for random / cost-aware assignment.
+- **Native tools, group-scoped.** Tools (web search, retrieval, KB query, Relata research) are granted per unit/seat and enforced — an ungranted tool is *absent* from that agent's toolset. Grants can be declarative or randomised; register your own with `hypermind.orgs.register_tool(...)`.
+- **Relata end-to-end.** Organisation → tenant; member → private memory session (agent kid); claims / disputes / reputation → tenant-scoped ledger rows; chain of custody → the Merkle log. Restart replays the whole org.
+
+Worked example: [`examples/org_university.py`](examples/org_university.py). Discover all presets via `hypermind.orgs.templates.list_templates()`.
+
+---
+
+## SimLab modes (the demo UI)
+
+**SimLab is a demo app**, not the core — a Vue web UI (bundled under `hypermind.simlab`) that visualises the same SDK primitives the `hypermind.orgs` engine drives programmatically. Use `hypermind.orgs` to build simulations; use SimLab to *watch* one. `hmctl simlab` ships 8 deliberation modes that exercise different protocol primitives:
 
 | Mode | One-liner |
 |---|---|

{hypermind-0.11.0 → hypermind-0.13.0}/examples/README.md

@@ -82,6 +82,12 @@ Read in order. Each builds on the previous one's mental model.
 
 Pick one that matches your domain.
 
+### Living-simulation engine (`hypermind.orgs`)
+
+| File | Domain | What it shows |
+|---|---|---|
+| [`org_university.py`](org_university.py) | Any network | Spin up a templated org (university / city / UNO / crowd), run research → cite → dispute → resolve → evolve, print a reputation + citation report. Per-agent models + group-scoped tools, persisted to Relata. |
+
 ### Pilot-shaped demonstrations
 
 | File | Domain | What it shows |

hypermind-0.13.0/examples/org_university.py

@@ -0,0 +1,66 @@
+"""THE STORY — a university researches a hard problem, and standing emerges.
+
+This is the ``hypermind.orgs`` living-simulation engine in ~15 lines: pick a
+preconfigured template, point it at a Relata instance and an LLM, and run. Over
+several rounds the departments publish findings, cite the strongest peers,
+peer-review (dispute) weak claims, and the professors ground results — so
+reputation, a citation graph, and a dispute ledger all emerge from agent
+behaviour rather than being scripted.
+
+Swap ``university`` for ``city_at_war``, ``foreign_policy_cabinet``,
+``un_security_council`` or ``internet_crowd`` to run a completely different
+scenario on the same engine — the only thing that changes is the org template
+and its interaction mode.
+
+PREREQUISITES
+  * A running Relata instance:   docker compose -f deploy/docker-compose.yml up -d relata
+  * export RELATA_URL=http://localhost:9090   RELATA_TOKEN=...
+  * export ANTHROPIC_API_KEY=...   (or use llm="openai" + OPENAI_API_KEY)
+
+Run with:   python -m examples.org_university
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+
+async def main() -> None:
+    from hypermind.orgs import OrgSim
+    from hypermind.orgs.templates import university
+
+    relata_url = os.environ.get("RELATA_URL")
+    if not relata_url:
+        raise SystemExit(
+            "Set RELATA_URL (and RELATA_TOKEN) to a running Relata instance. "
+            "See deploy/docker-compose.yml."
+        )
+
+    # Build an Anthropic client for the members to think with.
+    import anthropic
+
+    client = anthropic.AsyncAnthropic()  # reads ANTHROPIC_API_KEY
+
+    model = university(members=24)  # 2 departments, scaled to 24 people
+    sim = OrgSim(
+        model,
+        relata_url=relata_url,
+        relata_token=os.environ.get("RELATA_TOKEN"),
+        llm="anthropic",
+        llm_client=client,
+    )
+
+    report = await sim.simulate(
+        topic="What limits the accuracy of ab-initio protein folding?",
+        rounds=6,
+    )
+
+    report.print()
+    print("\nMost-cited papers:")
+    for c in report.most_cited(3):
+        print(f"  {c['citations_received']} cites  {c['by']} ({c['unit']})")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{hypermind-0.11.0 → hypermind-0.13.0}/pyproject.toml

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

hypermind-0.13.0/src/hypermind/orgs/__init__.py

@@ -0,0 +1,85 @@
+"""hypermind.orgs — an agentic living-simulation engine.
+
+Spin up a network of LLM-backed agents with roles, per-agent models, and
+group-scoped native tools, then run a research → publish → cite → dispute →
+resolve → learn → evolve loop persisted to Relata. One general engine expresses
+many scenarios (research, war, foreign policy, internet crowd) via pluggable
+interaction strategies.
+
+Quick start (preconfigured template)::
+
+    from hypermind.orgs.templates import university
+    from hypermind.orgs import OrgSim
+
+    model = university(members=24)
+    report = await OrgSim(model, relata_url="http://localhost:9090",
+                          llm="anthropic", llm_client=client).simulate(
+                              topic="protein folding", rounds=8)
+    report.print()
+
+The generic core (`OrgModel`/`Unit`/`Seat`) never imports the template library,
+so custom networks are first-class — see `hypermind.orgs.templates` for
+worked examples of the mapping.
+"""
+
+from __future__ import annotations
+
+from hypermind.orgs.groundtruth import (
+    CallableGroundTruth,
+    GroundTruth,
+    LLMJudgeGroundTruth,
+    StaticGroundTruth,
+)
+from hypermind.orgs.interaction import (
+    Adversarial,
+    Cooperative,
+    Crowd,
+    Interaction,
+    get_interaction,
+)
+from hypermind.orgs.metrics import ScoreCard, compute_scorecard
+from hypermind.orgs.model import (
+    DynamicsConfig,
+    OrgModel,
+    Seat,
+    Slot,
+    Unit,
+)
+from hypermind.orgs.report import MemberStanding, OrgReport
+from hypermind.orgs.sim import OrgSim
+from hypermind.orgs.tools import (
+    build_tool,
+    declarative_grants,
+    list_tools,
+    random_grants,
+    register_tool,
+    unregister_tool,
+)
+
+__all__ = [
+    "Adversarial",
+    "CallableGroundTruth",
+    "Cooperative",
+    "Crowd",
+    "DynamicsConfig",
+    "GroundTruth",
+    "Interaction",
+    "LLMJudgeGroundTruth",
+    "MemberStanding",
+    "OrgModel",
+    "OrgReport",
+    "OrgSim",
+    "ScoreCard",
+    "Seat",
+    "Slot",
+    "StaticGroundTruth",
+    "Unit",
+    "build_tool",
+    "compute_scorecard",
+    "declarative_grants",
+    "get_interaction",
+    "list_tools",
+    "random_grants",
+    "register_tool",
+    "unregister_tool",
+]

hypermind-0.13.0/src/hypermind/orgs/groundtruth.py

@@ -0,0 +1,126 @@
+"""Pluggable ground-truth oracles (#157).
+
+Reputation should reflect **real accuracy**, not a `confidence >= 0.5`
+heuristic. A ``GroundTruth`` resolves a published claim to a boolean outcome
+(or ``None`` = unknown → fall back to the interaction default). Feeding real
+outcomes into `oracle_resolve` makes reputation and the scorecard's Brier
+score meaningful, and enables backtesting ("did the crowd actually predict
+right?").
+
+Built-ins:
+  * ``StaticGroundTruth`` — known outcomes keyed by member label or topic.
+  * ``CallableGroundTruth`` — wrap any sync/async ``(topic, claim) -> bool|None``.
+  * ``LLMJudgeGroundTruth`` — an independent LLM judges each claim vs a rubric.
+
+All are injectable; the LLM judge takes a client (fake in tests).
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+from collections.abc import Awaitable, Callable
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class GroundTruth(Protocol):
+    async def resolve(self, topic: str, claim: dict[str, Any]) -> bool | None:
+        """Return True/False for a resolved claim, or None if unknown."""
+        ...
+
+
+class StaticGroundTruth:
+    """Fixed answers keyed by member label first, then topic.
+
+    ``answers`` maps a claim's ``by`` label (or the topic string) to a bool.
+    """
+
+    def __init__(self, answers: dict[str, bool]) -> None:
+        self._answers = dict(answers)
+
+    async def resolve(self, topic: str, claim: dict[str, Any]) -> bool | None:
+        by = claim.get("by")
+        if by in self._answers:
+            return self._answers[by]
+        return self._answers.get(topic)
+
+
+class CallableGroundTruth:
+    """Wrap any ``(topic, claim) -> bool | None`` (sync or async)."""
+
+    def __init__(
+        self,
+        fn: Callable[[str, dict[str, Any]], bool | None | Awaitable[bool | None]],
+    ) -> None:
+        self._fn = fn
+
+    async def resolve(self, topic: str, claim: dict[str, Any]) -> bool | None:
+        out = self._fn(topic, claim)
+        if inspect.isawaitable(out):
+            return await out
+        return out
+
+
+_JUDGE_SYSTEM = (
+    "You are an impartial evaluator. Given a question and a claim, decide "
+    "whether the claim is correct. Respond with a JSON object "
+    '{"correct": true|false} and nothing else.'
+)
+
+
+class LLMJudgeGroundTruth:
+    """An independent LLM scores each claim against an optional rubric.
+
+    ``client`` is an OpenAI-compatible async client; injectable so tests pass a
+    fake. Returns None on any parse/transport failure (→ interaction default).
+    """
+
+    def __init__(
+        self,
+        *,
+        client: Any,
+        model: str = "gpt-4o-mini",
+        rubric: str = "",
+        timeout_s: float = 30.0,
+    ) -> None:
+        self._client = client
+        self._model = model
+        self._rubric = rubric
+        self._timeout = timeout_s
+
+    async def resolve(self, topic: str, claim: dict[str, Any]) -> bool | None:
+        finding = claim.get("finding") or f"(confidence {claim.get('confidence')})"
+        rubric = f"\nRubric: {self._rubric}" if self._rubric else ""
+        user = (
+            f"Question: {topic}\nClaim: {finding}{rubric}\n"
+            'Is the claim correct? Reply as {"correct": true|false}.'
+        )
+        try:
+            resp = await self._client.chat.completions.create(
+                model=self._model,
+                messages=[
+                    {"role": "system", "content": _JUDGE_SYSTEM},
+                    {"role": "user", "content": user},
+                ],
+                response_format={"type": "json_object"},
+                timeout=self._timeout,
+            )
+            content = resp.choices[0].message.content or "{}"
+            verdict = json.loads(content).get("correct")
+            return bool(verdict) if verdict is not None else None
+        except Exception:
+            return None
+
+
+def as_ground_truth(
+    obj: GroundTruth | Callable[[str, dict[str, Any]], Any] | None,
+) -> GroundTruth | None:
+    """Normalise a GroundTruth, a plain callable, or None into a GroundTruth."""
+    if obj is None:
+        return None
+    if isinstance(obj, GroundTruth):
+        return obj
+    if callable(obj):
+        return CallableGroundTruth(obj)
+    raise TypeError(f"ground_truth must be a GroundTruth or callable, got {type(obj).__name__}")

hypermind-0.13.0/src/hypermind/orgs/interaction.py

@@ -0,0 +1,177 @@
+"""Interaction strategies — how members treat each other's claims each round.
+
+The engine (:mod:`hypermind.orgs.sim`) runs one general
+research → publish → cite → dispute → resolve loop. *How* each phase behaves is
+delegated to an :class:`Interaction` strategy, so the same loop expresses very
+different scenarios:
+
+* ``cooperative`` — cite freely across the org, dispute only on wide
+  contradiction (a university researching problem X).
+* ``adversarial`` — cite within your own unit, dispute rival units hard (a city
+  at war, rival factions, contested foreign policy).
+* ``crowd`` — many low-authority voices, synthesists aggregate, disputes are
+  rare (a what-if over an internet crowd).
+
+Subclass :class:`Interaction` and override a single method to customise one
+phase without rewriting the loop ("general loop + override hook").
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ClaimRec:
+    """A claim published this round, as seen by the interaction strategy."""
+
+    kid: bytes
+    member_label: str
+    member_kid: bytes
+    unit: str
+    role: str
+    confidence: float
+
+
+class Interaction:
+    """Default (cooperative) strategy. Override methods to change one phase."""
+
+    name = "cooperative"
+
+    # ---- publish -------------------------------------------------------
+    def publish_floor(self, *, role: str, base_floor: float) -> float:
+        """Confidence gate to publish, scaled by role.
+
+        Scouts surface early (lower bar); sceptics hold fire (higher bar).
+        """
+        if role == "scout":
+            return max(0.0, base_floor - 0.15)
+        if role == "sceptic":
+            return min(1.0, base_floor + 0.15)
+        return base_floor
+
+    # ---- cite ----------------------------------------------------------
+    def cite_targets(
+        self,
+        *,
+        member_unit: str,
+        member_role: str,
+        own_kid: bytes,
+        claims: list[ClaimRec],
+    ) -> list[bytes]:
+        """Which peer claims this member cites. Cooperative: the single
+        highest-confidence peer claim anywhere in the org."""
+        peers = [c for c in claims if c.kid != own_kid]
+        if not peers:
+            return []
+        best = max(peers, key=lambda c: c.confidence)
+        return [best.kid]
+
+    # ---- dispute -------------------------------------------------------
+    def should_dispute(
+        self, *, disputer_role: str, disputer_mean: float, claim: ClaimRec, gap: float
+    ) -> bool:
+        """Whether ``disputer`` challenges ``claim``. Cooperative: only
+        sceptics, only on a wide belief gap."""
+        if disputer_role != "sceptic":
+            return False
+        return abs(disputer_mean - claim.confidence) >= gap
+
+    # ---- resolve -------------------------------------------------------
+    def resolve_outcome(self, *, claim: ClaimRec, ground_truth: bool | None) -> bool:
+        """Ground-truth outcome for reputation back-prop. Default: caller's
+        signal, else 'confident claims are treated as correct'."""
+        if ground_truth is not None:
+            return ground_truth
+        return claim.confidence >= 0.5
+
+
+class Cooperative(Interaction):
+    name = "cooperative"
+
+
+class Adversarial(Interaction):
+    """Rival units: cite your own side, attack the other side."""
+
+    name = "adversarial"
+
+    def cite_targets(
+        self,
+        *,
+        member_unit: str,
+        member_role: str,
+        own_kid: bytes,
+        claims: list[ClaimRec],
+    ) -> list[bytes]:
+        # Cite the strongest claim from *your own* unit (rally your side).
+        allies = [c for c in claims if c.unit == member_unit and c.kid != own_kid]
+        if not allies:
+            return []
+        best = max(allies, key=lambda c: c.confidence)
+        return [best.kid]
+
+    def should_dispute(
+        self, *, disputer_role: str, disputer_mean: float, claim: ClaimRec, gap: float
+    ) -> bool:
+        # Anyone disputes a rival unit's claim if it diverges at all past a
+        # softened gap; sceptics are the most aggressive.
+        if claim.role == "oracle":
+            return False
+        effective_gap = gap * (0.5 if disputer_role == "sceptic" else 1.0)
+        return abs(disputer_mean - claim.confidence) >= effective_gap
+
+
+class Crowd(Interaction):
+    """Large, low-authority population; synthesists aggregate; few disputes."""
+
+    name = "crowd"
+
+    def publish_floor(self, *, role: str, base_floor: float) -> float:
+        # Crowds speak up readily; the bar is low except for the aggregator.
+        if role == "synthesist":
+            return base_floor
+        return max(0.0, base_floor - 0.3)
+
+    def cite_targets(
+        self,
+        *,
+        member_unit: str,
+        member_role: str,
+        own_kid: bytes,
+        claims: list[ClaimRec],
+    ) -> list[bytes]:
+        # Only synthesists aggregate — they cite the top few loudest voices.
+        if member_role != "synthesist":
+            return []
+        peers = sorted(
+            (c for c in claims if c.kid != own_kid),
+            key=lambda c: c.confidence,
+            reverse=True,
+        )
+        return [c.kid for c in peers[:3]]
+
+    def should_dispute(
+        self, *, disputer_role: str, disputer_mean: float, claim: ClaimRec, gap: float
+    ) -> bool:
+        # The crowd rarely disputes; only sceptics, only on very wide gaps.
+        if disputer_role != "sceptic":
+            return False
+        return abs(disputer_mean - claim.confidence) >= min(1.0, gap + 0.2)
+
+
+_PRESETS: dict[str, type[Interaction]] = {
+    "cooperative": Cooperative,
+    "adversarial": Adversarial,
+    "crowd": Crowd,
+}
+
+
+def get_interaction(name: str) -> Interaction:
+    """Instantiate a preset interaction strategy by name."""
+    try:
+        return _PRESETS[name]()
+    except KeyError:
+        raise ValueError(
+            f"unknown interaction {name!r}; presets: {sorted(_PRESETS)}. "
+            "Pass an Interaction subclass instance to override phases."
+        ) from None