hypermind 0.11.0__tar.gz → 0.12.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypermind
-Version: 0.11.0
+Version: 0.12.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.12.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.12.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.12.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.12.0}/pyproject.toml

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

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

@@ -0,0 +1,72 @@
+"""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.interaction import (
+    Adversarial,
+    Cooperative,
+    Crowd,
+    Interaction,
+    get_interaction,
+)
+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",
+    "Cooperative",
+    "Crowd",
+    "DynamicsConfig",
+    "Interaction",
+    "MemberStanding",
+    "OrgModel",
+    "OrgReport",
+    "OrgSim",
+    "Seat",
+    "Slot",
+    "Unit",
+    "build_tool",
+    "declarative_grants",
+    "get_interaction",
+    "list_tools",
+    "random_grants",
+    "register_tool",
+    "unregister_tool",
+]

hypermind-0.12.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

hypermind-0.12.0/src/hypermind/orgs/model.py

@@ -0,0 +1,246 @@
+"""Declarative organisation model — the generic core.
+
+An :class:`OrgModel` describes *what* an organisation looks like — its units
+(departments / districts / factions), the seats within each unit, and the
+HyperMind role + persona each seat plays — without any organisation-specific
+logic. The :class:`~hypermind.orgs.sim.OrgSim` engine turns a model into a
+running multi-agent simulation.
+
+Nothing here imports the template library or the engine, so the core stays
+dependency-free and every concrete org (university, hospital, UNO, ...) is
+just data.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+
+# The closed set of HyperMind roles a seat may map onto. Mirrors
+# ``hypermind.mind.roles`` (scout, sceptic, generalist, synthesist, mediator,
+# oracle). Kept as a plain frozenset so ``model.py`` has no mind-layer import.
+VALID_ROLES = frozenset({"scout", "sceptic", "generalist", "synthesist", "mediator", "oracle"})
+
+# Roles that adjudicate rather than publish primary claims. An org needs at
+# least one of these to resolve disputes and ground claims.
+RESOLVER_ROLES = frozenset({"oracle", "mediator"})
+
+
+@dataclass(frozen=True)
+class Seat:
+    """One kind of member within a unit.
+
+    ``authority`` (0..1) seeds the member's starting reputation weight, vouch
+    power, and LLM ``effective_n`` (higher authority → tighter calibration).
+    ``headcount`` is how many members occupy this seat *per unit*.
+
+    ``llm`` / ``model`` pin this seat's provider and model (mixed models in one
+    simulation); ``None`` inherits the simulation default. ``tools`` is this
+    seat's tool allowlist — names resolved against the tool registry; members
+    can only call tools granted to their seat or their unit.
+    """
+
+    title: str
+    role: str = "generalist"
+    system: str | None = None
+    authority: float = 0.5
+    headcount: int = 1
+    llm: str | None = None
+    model: str | None = None
+    tools: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if self.role not in VALID_ROLES:
+            raise ValueError(
+                f"seat {self.title!r}: unknown role {self.role!r}; "
+                f"valid roles are {sorted(VALID_ROLES)}"
+            )
+        if not 0.0 <= self.authority <= 1.0:
+            raise ValueError(
+                f"seat {self.title!r}: authority must be in [0, 1], got {self.authority}"
+            )
+        if self.headcount < 1:
+            raise ValueError(f"seat {self.title!r}: headcount must be >= 1, got {self.headcount}")
+        if not isinstance(self.tools, tuple):
+            object.__setattr__(self, "tools", tuple(self.tools))
+
+
+@dataclass(frozen=True)
+class Unit:
+    """A group of seats — maps to one HyperMind room within the org namespace.
+
+    ``tools`` granted at the unit level apply to every seat in the unit (union
+    with each seat's own allowlist) — the natural way to say "the intel
+    department may use satellite imagery, the law department may not."
+    """
+
+    name: str
+    seats: tuple[Seat, ...] = ()
+    tools: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not self.name.strip():
+            raise ValueError("unit name is required")
+        if not self.seats:
+            raise ValueError(f"unit {self.name!r} has no seats")
+        # Normalise lists to tuples so the dataclass stays hashable/frozen.
+        if not isinstance(self.seats, tuple):
+            object.__setattr__(self, "seats", tuple(self.seats))
+        if not isinstance(self.tools, tuple):
+            object.__setattr__(self, "tools", tuple(self.tools))
+
+
+# Interaction modes shape how members treat each other's claims in the loop.
+#   cooperative — cite freely, dispute only on wide contradiction (research).
+#   adversarial — cite within your own unit, dispute across units aggressively
+#                 (war / rival factions / contested policy).
+#   crowd       — many low-authority voices, a synthesist aggregates, minimal
+#                 disputes (what-if over an internet crowd).
+VALID_INTERACTIONS = frozenset({"cooperative", "adversarial", "crowd"})
+
+
+@dataclass(frozen=True)
+class DynamicsConfig:
+    """Knobs for the research → learn → evolve loop."""
+
+    rounds: int = 5
+    publish_floor: float = 0.7
+    dispute_gap: float = 0.4
+    oracle_resolve_frac: float = 0.3
+    vouch_juniors: bool = True
+    evolve: bool = True
+    interaction: str = "cooperative"
+
+    def __post_init__(self) -> None:
+        if self.rounds < 1:
+            raise ValueError(f"rounds must be >= 1, got {self.rounds}")
+        for name in ("publish_floor", "dispute_gap", "oracle_resolve_frac"):
+            v = getattr(self, name)
+            if not 0.0 <= v <= 1.0:
+                raise ValueError(f"{name} must be in [0, 1], got {v}")
+        if self.interaction not in VALID_INTERACTIONS:
+            raise ValueError(
+                f"interaction must be one of {sorted(VALID_INTERACTIONS)}, got {self.interaction!r}"
+            )
+
+
+@dataclass(frozen=True)
+class Slot:
+    """A concrete member position produced by :meth:`OrgModel.roster`."""
+
+    unit: str
+    seat: Seat
+    index: int  # 0-based occupant index within (unit, seat)
+
+    @property
+    def label(self) -> str:
+        return f"{self.unit}/{self.seat.title}#{self.index + 1}"
+
+
+@dataclass(frozen=True)
+class OrgModel:
+    """A complete, generic organisation definition."""
+
+    name: str
+    namespace: str
+    units: tuple[Unit, ...] = ()
+    lexicon: dict[str, str] = field(default_factory=dict)
+    dynamics: DynamicsConfig = field(default_factory=DynamicsConfig)
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.units, tuple):
+            object.__setattr__(self, "units", tuple(self.units))
+        self.validate()
+
+    def validate(self) -> None:
+        if not self.name.strip():
+            raise ValueError("org name is required")
+        if not self.namespace.strip():
+            raise ValueError("org namespace is required")
+        if not self.units:
+            raise ValueError(f"org {self.name!r} has no units")
+        names = [u.name for u in self.units]
+        if len(names) != len(set(names)):
+            raise ValueError(f"org {self.name!r} has duplicate unit names: {names}")
+        roles = {s.role for u in self.units for s in u.seats}
+        if not (roles & RESOLVER_ROLES):
+            raise ValueError(
+                f"org {self.name!r} needs at least one oracle or mediator seat "
+                "to resolve disputes and ground claims"
+            )
+
+    def roster(self, members: int | None = None) -> list[Slot]:
+        """Expand the model into concrete member slots.
+
+        With ``members=None`` every seat contributes exactly its ``headcount``.
+        With an explicit ``members`` target, seat headcounts are scaled
+        proportionally (largest-remainder) to hit the target while keeping at
+        least one occupant per seat, so no role silently disappears.
+        """
+        base = [
+            Slot(unit=u.name, seat=s, index=i)
+            for u in self.units
+            for s in u.seats
+            for i in range(s.headcount)
+        ]
+        if members is None or members == len(base):
+            return base
+        if members < 1:
+            raise ValueError(f"members must be >= 1, got {members}")
+
+        seats = [(u.name, s) for u in self.units for s in u.seats]
+        n_seats = len(seats)
+        if members < n_seats:
+            raise ValueError(
+                f"members={members} is fewer than the {n_seats} distinct seats in "
+                f"{self.name!r}; each seat needs at least one occupant"
+            )
+        # Proportional scale on the base headcounts, floored at 1.
+        base_total = len(base)
+        weights = [s.headcount for _, s in seats]
+        raw = [members * w / base_total for w in weights]
+        counts = [max(1, int(x)) for x in raw]
+        # Distribute the remainder by largest fractional part until we hit target.
+        deficit = members - sum(counts)
+        order = sorted(range(n_seats), key=lambda i: raw[i] - int(raw[i]), reverse=True)
+        i = 0
+        while deficit > 0 and order:
+            counts[order[i % n_seats]] += 1
+            deficit -= 1
+            i += 1
+        while deficit < 0:  # target below floors — trim the largest counts
+            j = max(range(n_seats), key=lambda k: counts[k])
+            if counts[j] <= 1:
+                break  # pragma: no cover - unreachable: members >= n_seats guarantees a trimmable seat
+            counts[j] -= 1
+            deficit += 1
+        return [
+            Slot(unit=unit, seat=seat, index=i)
+            for (unit, seat), c in zip(seats, counts, strict=True)
+            for i in range(c)
+        ]
+
+    def relabel(self, key: str, default: str) -> str:
+        """Look up a display term from the lexicon (e.g. 'claim' → 'paper')."""
+        return self.lexicon.get(key, default)
+
+    def scaled(self, members: int) -> OrgModel:
+        """Return a copy whose seat headcounts realise ``members`` occupants.
+
+        Handy for templates: ``university(members=40)`` calls this so the
+        returned model's ``roster()`` (no arg) already yields 40 slots.
+        """
+        slots = self.roster(members)
+        counts: dict[tuple[str, str], int] = {}
+        for sl in slots:
+            counts[(sl.unit, sl.seat.title)] = counts.get((sl.unit, sl.seat.title), 0) + 1
+        new_units = tuple(
+            replace(
+                u,
+                seats=tuple(
+                    replace(s, headcount=counts.get((u.name, s.title), s.headcount))
+                    for s in u.seats
+                ),
+            )
+            for u in self.units
+        )
+        return replace(self, units=new_units)