hypermind 0.24.0__tar.gz → 0.30.0__tar.gz

{hypermind-0.24.0 → hypermind-0.30.0}/CHANGELOG.md

@@ -16,6 +16,18 @@ changes only on major-version bumps.
 
 _Current trunk._
 
+## [0.30.0] — 2026-07-08
+
+### Added
+- **Live simulation dashboard** (#196) — a colourful, animated Rich view of a running sim: round progress bar, glowing stat cards (claims/citations/disputes/resolves), a per-round claims sparkline, a per-unit tally, and a colour-coded live activity feed. Turn on with `hmctl orgs simulate --live` / `ask --live`.
+- **Cross-shard grounding** (#195) — in a distributed run, agents now ground on *other shards'* findings pulled from the shared Relata ledger (`RelataBackend.recent_findings`, `OrgSim(cross_shard=True)`, default-on in the distributed worker), so a sharded run reasons like one swarm instead of N isolated ones. (Cross-shard citation/dispute graph + reputation unification is tracked as a follow-up.)
+- **`hmctl orgs` — no-code CLI for the living-simulation engine.** Run the whole engine from the shell:
+  - `hmctl orgs templates` — list presets.
+  - `hmctl orgs simulate --template university --members 24 --rounds 6 --topic "…" [--html report.html]`.
+  - `hmctl orgs ask "question" --template … [--samples N] [--no-quality]` — study→ask with the quality rubrics **on by default** (grounding, hallucination, calibration, native ledger rubrics).
+  - `hmctl orgs distributed --template … --members 10000 --workers 8 --topic "…"` — sharded run; the master provisions Relata + reassigns failures.
+  - LLM + Relata configured via flags/env (`--llm`, `--llm-model`, `--base-url`, `--api-key-env`, `--relata-url`); Hm* types auto-provisioned.
+
 ## [0.23.0] — 2026-07-08
 
 ### Added

{hypermind-0.24.0 → hypermind-0.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypermind
-Version: 0.24.0
+Version: 0.30.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
@@ -237,6 +237,8 @@ report.print()        # reputation ranking · citation graph · dispute ledger
 - **Answer quality, natively.** `await sim.assess(question)` returns a `QualityReport` scoring grounding, hallucination rate, calibration (Brier), self-consistency, and hm-native rubrics that are *verifiable from the signed ledger* — provenance coverage, dispute exposure, reputation-weighted support. All rubrics on by default; missing deps (judge / ground-truth) degrade to informational notes.
 - **Scales like Locust.** `OrgSim(lightweight=True)` caps RAM to O(members), not O(records); Relata writes are batched. For horizontal scale, `hypermind.orgs.distributed` runs a **master/worker** control plane — shard a swarm across processes or machines against the shared Relata namespace, merged into one report (`python -m hypermind.orgs.distributed master/worker`, or `run_distributed(...)`).
 
+- **No-code CLI.** `hmctl orgs` runs the whole engine from the shell: `hmctl orgs templates`, `hmctl orgs simulate --template university --members 24 --topic "…"`, `hmctl orgs ask "…" --template university` (study→ask + quality rubrics on by default), and `hmctl orgs distributed --members 10000 --workers 8 --topic "…"`.
+
 Worked example: [`examples/org_university.py`](examples/org_university.py). Discover all presets via `hypermind.orgs.templates.list_templates()`.
 
 ---

{hypermind-0.24.0 → hypermind-0.30.0}/README.md

@@ -149,6 +149,8 @@ report.print()        # reputation ranking · citation graph · dispute ledger
 - **Answer quality, natively.** `await sim.assess(question)` returns a `QualityReport` scoring grounding, hallucination rate, calibration (Brier), self-consistency, and hm-native rubrics that are *verifiable from the signed ledger* — provenance coverage, dispute exposure, reputation-weighted support. All rubrics on by default; missing deps (judge / ground-truth) degrade to informational notes.
 - **Scales like Locust.** `OrgSim(lightweight=True)` caps RAM to O(members), not O(records); Relata writes are batched. For horizontal scale, `hypermind.orgs.distributed` runs a **master/worker** control plane — shard a swarm across processes or machines against the shared Relata namespace, merged into one report (`python -m hypermind.orgs.distributed master/worker`, or `run_distributed(...)`).
 
+- **No-code CLI.** `hmctl orgs` runs the whole engine from the shell: `hmctl orgs templates`, `hmctl orgs simulate --template university --members 24 --topic "…"`, `hmctl orgs ask "…" --template university` (study→ask + quality rubrics on by default), and `hmctl orgs distributed --members 10000 --workers 8 --topic "…"`.
+
 Worked example: [`examples/org_university.py`](examples/org_university.py). Discover all presets via `hypermind.orgs.templates.list_templates()`.
 
 ---

{hypermind-0.24.0 → hypermind-0.30.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypermind"
-version = "0.24.0"
+version = "0.30.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.24.0 → hypermind-0.30.0}/src/hmctl/cli.py

@@ -39,6 +39,12 @@ def main() -> None:
     """HyperMind conformance CLI."""
 
 
+# `hmctl orgs …` — run the living-simulation engine with no code.
+from hmctl.orgs_cmd import orgs as _orgs_group  # noqa: E402
+
+main.add_command(_orgs_group, name="orgs")
+
+
 @main.command()
 @click.option(
     "--check",

hypermind-0.30.0/src/hmctl/dashboard.py

@@ -0,0 +1,178 @@
+"""Live, colourful terminal dashboard for a running OrgSim (#196).
+
+Drives off OrgSim's ``on_event`` stream (round_start / publish / cite / dispute /
+resolve / round_end) and paints a Rich live view: a round progress bar, glowing
+stat cards, a per-round claims sparkline/bar-chart, a per-unit tally, and a
+colour-coded activity feed. Pass ``dashboard.handle`` as ``on_event=`` and run
+the sim inside ``with dashboard:``.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict, deque
+from typing import Any
+
+from rich.align import Align
+from rich.console import Console, Group
+from rich.live import Live
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+_BLOCKS = " ▁▂▃▄▅▆▇█"
+_PALETTE = ["#00e5ff", "#00ff9c", "#ffd166", "#ff5d8f", "#a78bfa", "#7dd3fc"]
+_EVENT_STYLE = {
+    "publish": ("📄", "bold #00ff9c"),
+    "cite": ("🔗", "bold #00e5ff"),
+    "dispute": ("⚖️", "bold #ffd166"),
+    "resolve": ("✓", "bold #a78bfa"),
+    "tool_call": ("🛠", "bold #7dd3fc"),
+}
+
+
+def _spark(vals: list[int], width: int = 32) -> Text:
+    if not vals:
+        return Text("—", style="grey37")
+    tail = vals[-width:]
+    mx = max(tail) or 1
+    t = Text()
+    for i, v in enumerate(tail):
+        ch = _BLOCKS[min(8, int(v / mx * 8))]
+        t.append(ch, style=_PALETTE[i % len(_PALETTE)])
+    return t
+
+
+class SimDashboard:
+    """A Rich live dashboard fed by OrgSim events."""
+
+    def __init__(
+        self,
+        *,
+        total_rounds: int,
+        org: str = "org",
+        topic: str = "",
+        console: Console | None = None,
+    ) -> None:
+        self.console = console or Console()
+        self.total = max(1, total_rounds)
+        self.org = org
+        self.topic = topic
+        self.round = 0
+        self.counts: dict[str, int] = defaultdict(int)
+        self.per_round: dict[int, int] = defaultdict(int)
+        self.per_unit: dict[str, int] = defaultdict(int)
+        self.feed: deque[Text] = deque(maxlen=9)
+        self._live: Live | None = None
+
+    def __enter__(self) -> SimDashboard:
+        self._live = Live(self._render(), console=self.console, refresh_per_second=12, screen=False)
+        self._live.__enter__()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        if self._live is not None:
+            self._live.update(self._render())
+            self._live.__exit__(*exc)
+
+    # OrgSim on_event sink (sync — fast, no awaiting).
+    def handle(self, ev: dict[str, Any]) -> None:
+        e = ev.get("event", "")
+        if e == "round_start":
+            self.round = int(ev.get("round", self.round)) + 1
+        elif e in _EVENT_STYLE:
+            self.counts[e] += 1
+            if e == "publish":
+                self.per_round[self.round] += 1
+                if ev.get("unit"):
+                    self.per_unit[ev["unit"]] += 1
+            self._push(ev, e)
+        self._refresh()
+
+    def _push(self, ev: dict[str, Any], e: str) -> None:
+        icon, style = _EVENT_STYLE[e]
+        who = str(ev.get("by", ev.get("unit", "")))
+        extra = ""
+        if e == "publish" and ev.get("confidence") is not None:
+            extra = f"  conf {ev['confidence']:.2f}"
+        elif e == "resolve":
+            extra = f"  → {'✓ correct' if ev.get('outcome') else '✗ wrong'}"
+        line = Text(f" r{self.round}  ", style="grey42")
+        line.append(f"{icon} {e:<8}", style=style)
+        line.append(f" {who}{extra}", style="grey70")
+        self.feed.append(line)
+
+    def _refresh(self) -> None:
+        if self._live is not None:
+            self._live.update(self._render())
+
+    # --- rendering --------------------------------------------------------
+    def _bar(self, frac: float, width: int = 44) -> Text:
+        filled = int(max(0.0, min(1.0, frac)) * width)
+        t = Text()
+        for i in range(width):
+            t.append(
+                "█" if i < filled else "─",
+                style=_PALETTE[i % len(_PALETTE)] if i < filled else "grey30",
+            )
+        return t
+
+    def _cards(self) -> Table:
+        cards = Table.grid(expand=True, padding=(0, 1))
+        cards.add_row(
+            self._card("📄 claims", self.counts["publish"], "#00ff9c"),
+            self._card("🔗 citations", self.counts["cite"], "#00e5ff"),
+            self._card("⚖️ disputes", self.counts["dispute"], "#ffd166"),
+            self._card("✓ resolves", self.counts["resolve"], "#a78bfa"),
+        )
+        return cards
+
+    def _card(self, label: str, value: int, colour: str) -> Panel:
+        body = Align.center(Text(str(value), style=f"bold {colour}"))
+        return Panel(body, title=label, border_style=colour, padding=(0, 1))
+
+    def _units(self) -> Text:
+        if not self.per_unit:
+            return Text("  (waiting for claims…)", style="grey37")
+        mx = max(self.per_unit.values()) or 1
+        t = Text()
+        for i, (unit, n) in enumerate(sorted(self.per_unit.items(), key=lambda kv: -kv[1])[:6]):
+            colour = _PALETTE[i % len(_PALETTE)]
+            bar = "█" * int(n / mx * 24) or "▏"
+            t.append(f"  {unit[:16]:<16} ", style="grey70")
+            t.append(bar, style=colour)
+            t.append(f" {n}\n", style=colour)
+        return t
+
+    def _render(self) -> Panel:
+        frac = self.round / self.total if self.total else 0.0
+        header = Text()
+        header.append("⬡ HyperMind  ", style="bold #00e5ff")
+        header.append(self.org, style="bold white")
+        if self.topic:
+            header.append(f"  ·  {self.topic[:60]}", style="grey62")
+
+        prog = Text()
+        prog.append(f"round {min(self.round, self.total)}/{self.total}  ", style="bold white")
+        prog.append_text(self._bar(frac))
+        prog.append(f"  {int(frac * 100):>3}%", style="bold #00ff9c")
+
+        spark = Text("claims/round  ", style="grey62")
+        spark.append_text(_spark([self.per_round[i] for i in range(1, self.round + 1)]))
+
+        feed = Group(*self.feed) if self.feed else Text("  (no activity yet)", style="grey37")
+
+        body = Group(
+            header,
+            Text(""),
+            prog,
+            Text(""),
+            self._cards(),
+            Text(""),
+            Panel(self._units(), title="per-unit claims", border_style="grey35", padding=(0, 0)),
+            spark,
+            Text(""),
+            Panel(feed, title="live activity", border_style="grey35", padding=(0, 1)),
+        )
+        return Panel(
+            body, border_style="#00e5ff", title="live simulation", subtitle="hypermind.orgs"
+        )

hypermind-0.30.0/src/hmctl/orgs_cmd.py

@@ -0,0 +1,310 @@
+"""`hmctl orgs` — run the hypermind.orgs living-simulation engine, no code.
+
+Turns the engine into shell commands: list templates, run a simulation, ask a
+studied swarm a question (with quality rubrics on by default), or run it
+distributed across workers. LLM + Relata are configured via flags/env, not code.
+
+    hmctl orgs templates
+    hmctl orgs simulate --template university --members 24 --rounds 6 --topic "..."
+    hmctl orgs ask "what limits protein folding?" --template university
+    hmctl orgs distributed --template university --members 10000 --workers 8 --topic "..."
+
+Env used as defaults: RELATA_URL, RELATA_TOKEN, OPENAI_API_KEY / OPENAI_BASE_URL.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import html as _html
+import os
+from typing import Any
+
+import click
+
+
+def _list_templates() -> list[str]:
+    from hypermind.orgs.templates import list_templates
+
+    return sorted(list_templates())
+
+
+def _build_model(template: str, members: int | None, namespace: str) -> Any:
+    from hypermind.orgs.templates import get_template
+
+    if template not in _list_templates():
+        raise click.ClickException(
+            f"unknown template {template!r}; choose one of: {', '.join(_list_templates())}"
+        )
+    factory = get_template(template)
+    return (
+        factory(members=members, namespace=namespace) if members else factory(namespace=namespace)
+    )
+
+
+def build_llm_client(
+    llm: str, base_url: str | None, api_key_env: str | None, *, async_: bool
+) -> Any:
+    """Build an LLM client from flags/env. Split out so tests can monkeypatch it."""
+    if llm == "openai":
+        import openai
+
+        key = os.environ.get(api_key_env or "OPENAI_API_KEY")
+        if not key:
+            raise click.ClickException(
+                f"no API key in ${api_key_env or 'OPENAI_API_KEY'}; export it or pass --api-key-env"
+            )
+        url = base_url or os.environ.get("OPENAI_BASE_URL")
+        return (openai.AsyncOpenAI if async_ else openai.OpenAI)(base_url=url, api_key=key)
+    if llm == "anthropic":
+        import anthropic
+
+        key = os.environ.get(api_key_env or "ANTHROPIC_API_KEY")
+        if not key:
+            raise click.ClickException(f"no API key in ${api_key_env or 'ANTHROPIC_API_KEY'}")
+        return (anthropic.AsyncAnthropic if async_ else anthropic.Anthropic)(api_key=key)
+    raise click.ClickException(f"unknown --llm {llm!r} (expected 'openai' or 'anthropic')")
+
+
+def _require_relata(relata_url: str | None) -> str:
+    url = relata_url or os.environ.get("RELATA_URL")
+    if not url:
+        raise click.ClickException(
+            "no Relata URL — pass --relata-url or set RELATA_URL "
+            "(start one with: docker compose -f deploy/docker-compose.yml up -d relata)"
+        )
+    return url
+
+
+def _llm_opts(fn):
+    """Shared LLM/Relata options for the run commands."""
+    opts = [
+        click.option("--template", default="university", help="preset org (see `orgs templates`)"),
+        click.option("--members", type=int, default=None, help="scale the org to N members"),
+        click.option("--rounds", type=int, default=6, help="research rounds"),
+        click.option("--namespace", default=None, help="Relata namespace (default: template name)"),
+        click.option("--relata-url", default=None, help="Relata URL (default: $RELATA_URL)"),
+        click.option("--relata-token", default=None, help="Relata bearer (default: $RELATA_TOKEN)"),
+        click.option("--llm", default="openai", help="openai | anthropic"),
+        click.option("--llm-model", default=None, help="model id (e.g. openai/gpt-4o-mini)"),
+        click.option("--base-url", default=None, help="LLM base URL (e.g. OpenRouter)"),
+        click.option("--api-key-env", default=None, help="env var holding the API key"),
+    ]
+    for o in reversed(opts):
+        fn = o(fn)
+    return fn
+
+
+def _make_dashboard(live: bool, rounds: int, org: str, topic: str):
+    if not live:
+        return None
+    from hmctl.dashboard import SimDashboard
+
+    return SimDashboard(total_rounds=rounds, org=org, topic=topic)
+
+
+def _run(go, dash):
+    """Run the async coro, wrapping it in the live dashboard when present."""
+    if dash is None:
+        return asyncio.run(go())
+    with dash:
+        return asyncio.run(go())
+
+
+@click.group()
+def orgs() -> None:
+    """Run the hypermind.orgs living-simulation engine (no code)."""
+
+
+@orgs.command("templates")
+def templates_cmd() -> None:
+    """List the preconfigured org templates."""
+    for name in _list_templates():
+        click.echo(name)
+
+
+def _write_html(report: Any, path: str) -> None:
+    rows = "".join(
+        f"<tr><td>{s.reputation:.2f}</td><td>{_html.escape(s.label)}</td>"
+        f"<td>{_html.escape(s.role)}</td><td>{s.claims}</td>"
+        f"<td>{s.citations_received}</td><td>{s.disputes_received}</td></tr>"
+        for s in report.standings
+    )
+    sc = report.scorecard
+    with open(path, "w") as f:
+        f.write(
+            f"<!doctype html><meta charset=utf-8><title>{_html.escape(report.org)}</title>"
+            "<style>body{font:14px system-ui;margin:2rem;max-width:900px}"
+            "table{border-collapse:collapse;width:100%}td,th{border:1px solid #ccc;padding:.4rem}"
+            "th{background:#f4f4f4;text-align:left}</style>"
+            f"<h1>{_html.escape(report.org)} — {_html.escape(report.topic)}</h1>"
+            f"<p>{report.rounds} rounds · {len(report.standings)} members · "
+            f"{sc['claims']} claims · {sc['citations']} citations · "
+            f"Brier {sc['brier_mean']}</p>"
+            "<table><tr><th>rep</th><th>member</th><th>role</th><th>claims</th>"
+            f"<th>cites</th><th>disputes</th></tr>{rows}</table>"
+        )
+
+
+@orgs.command("simulate")
+@_llm_opts
+@click.option("--topic", required=True, help="what the org researches")
+@click.option("--html", "html_path", default=None, help="write an HTML report to PATH")
+@click.option("--live", is_flag=True, help="show a live colourful dashboard while it runs")
+def simulate_cmd(
+    template,
+    members,
+    rounds,
+    namespace,
+    relata_url,
+    relata_token,
+    llm,
+    llm_model,
+    base_url,
+    api_key_env,
+    topic,
+    html_path,
+    live,
+) -> None:
+    """Run a simulation and print (or save) the report."""
+    url = _require_relata(relata_url)
+    ns = namespace or template
+    model = _build_model(template, members, ns)
+    client = build_llm_client(llm, base_url, api_key_env, async_=True)
+    dash = _make_dashboard(live, rounds, model.name, topic)
+
+    async def go():
+        from hypermind.orgs import OrgSim
+        from hypermind.orgs.distributed import provision_hm_types
+
+        provision_hm_types(url, namespace=ns, token=relata_token)
+        sim = OrgSim(
+            model,
+            relata_url=url,
+            relata_token=relata_token,
+            llm=llm,
+            llm_model=llm_model,
+            llm_client=client,
+            on_event=dash.handle if dash else None,
+        )
+        return await sim.simulate(topic=topic, rounds=rounds)
+
+    report = _run(go, dash)
+    report.print()
+    if html_path:
+        _write_html(report, html_path)
+        click.echo(f"\nwrote {html_path}")
+
+
+@orgs.command("ask")
+@_llm_opts
+@click.argument("question")
+@click.option("--topic", default=None, help="study topic (default: the question)")
+@click.option("--samples", type=int, default=1, help="ask N times (enables self-consistency)")
+@click.option("--quality/--no-quality", default=True, help="score the answer (on by default)")
+@click.option("--live", is_flag=True, help="show a live colourful dashboard during study")
+def ask_cmd(
+    template,
+    members,
+    rounds,
+    namespace,
+    relata_url,
+    relata_token,
+    llm,
+    llm_model,
+    base_url,
+    api_key_env,
+    question,
+    topic,
+    samples,
+    quality,
+    live,
+) -> None:
+    """Study a topic, then ask the swarm — with quality rubrics on by default."""
+    url = _require_relata(relata_url)
+    ns = namespace or template
+    model = _build_model(template, members, ns)
+    client = build_llm_client(llm, base_url, api_key_env, async_=True)
+    dash = _make_dashboard(live, rounds, model.name, topic or question)
+
+    async def go():
+        from hypermind.orgs import OrgSim
+        from hypermind.orgs.distributed import provision_hm_types
+        from hypermind.orgs.quality import llm_judge
+
+        provision_hm_types(url, namespace=ns, token=relata_token)
+        sim = OrgSim(
+            model,
+            relata_url=url,
+            relata_token=relata_token,
+            llm=llm,
+            llm_model=llm_model,
+            llm_client=client,
+            on_event=dash.handle if dash else None,
+        )
+        async with sim:
+            await sim.study(topic or question, rounds=rounds)
+            answer = await sim.ask(question)
+            report = None
+            if quality:
+                judge = None
+                if llm == "openai":  # grounding/hallucination need a sync judge client
+                    judge = llm_judge(
+                        build_llm_client(llm, base_url, api_key_env, async_=False),
+                        model=llm_model or "openai/gpt-4o",
+                    )
+                report = await sim.assess(question, judge=judge, samples=samples)
+            return answer, report
+
+    answer, report = _run(go, dash)
+    answer.print()
+    if report is not None:
+        report.print()
+
+
+@orgs.command("distributed")
+@_llm_opts
+@click.option("--topic", required=True, help="what the org researches")
+@click.option("--workers", type=int, default=4, help="in-process workers to shard across")
+@click.option("--html", "html_path", default=None, help="write an HTML report to PATH")
+def distributed_cmd(
+    template,
+    members,
+    rounds,
+    namespace,
+    relata_url,
+    relata_token,
+    llm,
+    llm_model,
+    base_url,
+    api_key_env,
+    topic,
+    workers,
+    html_path,
+) -> None:
+    """Run distributed across workers (master drives Relata + reassigns failures)."""
+    url = _require_relata(relata_url)
+    ns = namespace or template
+    if not members:
+        raise click.ClickException("--members is required for a distributed run")
+    model = _build_model(template, None, ns)
+
+    async def go():
+        from hypermind.orgs.distributed import run_distributed
+
+        cfg = {
+            "llm": llm,
+            "llm_model": llm_model,
+            "base_url": base_url,
+            "api_key_env": api_key_env,
+            "relata_url": url,
+            "relata_token": relata_token,
+        }
+        return await run_distributed(
+            model, topic, members=members, rounds=rounds, workers=workers, config=cfg
+        )
+
+    report = asyncio.run(go())
+    report.print()
+    if html_path:
+        _write_html(report, html_path)
+        click.echo(f"\nwrote {html_path}")

{hypermind-0.24.0 → hypermind-0.30.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.24.0"
+__version__ = "0.30.0"
 
 #: SLSA build-provenance level committed for every release artefact.
 #: Cosign keyless signing + slsa-github-generator + PEP 740 attestations

{hypermind-0.24.0 → hypermind-0.30.0}/src/hypermind/orgs/distributed/worker.py

@@ -41,6 +41,7 @@ async def default_shard_runner(spec: dict[str, Any]) -> dict[str, Any]:
         llm_model=cfg.get("llm_model"),
         llm_client=_build_llm_client(provider, cfg),
         lightweight=True,
+        cross_shard=cfg.get("cross_shard", True),  # ground on other shards via Relata (#195)
         members=int(spec["members"]),
         max_concurrency=int(cfg.get("max_concurrency", 16)),
         write_batch_size=int(cfg.get("write_batch_size", 64)),

{hypermind-0.24.0 → hypermind-0.30.0}/src/hypermind/orgs/sim.py

@@ -120,6 +120,7 @@ class OrgSim:
         max_concurrency: int = 16,
         write_batch_size: int = 64,
         lightweight: bool = False,
+        cross_shard: bool = False,
         claims_window: int = 4096,
         retrieval_k: int = 5,
         retriever: Callable[[str, int], list[tuple[str, str]]] | None = None,
@@ -189,6 +190,11 @@ class OrgSim:
         # 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)
+        # #195: when sharded across workers, pull peers' findings from the shared
+        # Relata ledger each round so agents ground on OTHER shards, not just
+        # their own in-process window. Refreshed once per round (bounded query).
+        self._cross_shard = bool(cross_shard)
+        self._cross_peers: list[tuple[str, str]] = []
         self._member_by_kid: dict[bytes, Member] = {}  # O(1) resolve lookups
         self._observe_top_k = 12  # deliberator: observe only the top-k peers
         self._retrieval_k = max(1, retrieval_k)  # RAG depth for recall + peers
@@ -596,6 +602,14 @@ class OrgSim:
             if getattr(iv, "round", None) == r:
                 await iv.apply(self)
         await self._emit("round_start", round=r, members=len(self._members))
+        # #195: refresh cross-shard peers from the shared ledger (once per round).
+        if self._cross_shard and self._backend is not None:
+            try:
+                self._cross_peers = await asyncio.to_thread(
+                    self._backend.recent_findings, self._retrieval_k * 4
+                )
+            except Exception:
+                self._cross_peers = []
         # 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).
@@ -697,7 +711,19 @@ class OrgSim:
         per-round loop, where 'recent' == 'this round's peers'."""
         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]]
+        local = [f"{label}: {text}" for label, _unit, _conf, text in peers[:limit]]
+        if not self._cross_peers:
+            return local
+        # Cross-shard peers (from the shared ledger) fill the rest of the budget,
+        # deduped against the local window — this is what makes a sharded run
+        # ground like one swarm instead of N isolated ones (#195).
+        seen = {t.split(": ", 1)[-1] for t in local}
+        shared = [
+            f"{by}: {finding}"
+            for by, finding in self._cross_peers
+            if by != m.label and finding not in seen
+        ]
+        return (local + shared)[: max(limit, self._retrieval_k)]
 
     def mention_graph(self) -> Any:
         """The claim↔entity graph built from findings (graph/identity RAG)."""

{hypermind-0.24.0 → hypermind-0.30.0}/src/hypermind/storage/relata.py

@@ -148,6 +148,36 @@ class RelataBackend:
             self._obj.batch_upsert("HmClaim", self._claim_buf)
             self._claim_buf = []
 
+    def recent_findings(self, limit: int = 64) -> list[tuple[str, str]]:
+        """Recent ``(author_label, finding)`` pairs from the shared ledger.
+
+        Decodes the most-recent claim payloads (across *all* writers in this
+        namespace) so a distributed worker can ground its agents on peers'
+        findings from other shards — cross-shard knowledge flow (#195). Only
+        primary claims (``record_type == "SEAL"``) with a finding are returned.
+        """
+        import cbor2
+
+        from hypermind.wire import SignedStatement
+
+        self.flush_claims()
+        rows = self._rows(
+            f"SELECT wire_b64 FROM HmClaim ORDER BY created_ms DESC LIMIT {int(max(1, limit))}"
+        )
+        out: list[tuple[str, str]] = []
+        for r in rows:
+            try:
+                stmt = SignedStatement.from_bytes(base64.b64decode(r["wire_b64"]))
+                if stmt.record_type != "SEAL":
+                    continue
+                user = (cbor2.loads(stmt.payload) or {}).get("payload") or {}
+                by, finding = user.get("by"), user.get("finding")
+                if by and finding:
+                    out.append((str(by), str(finding)))
+            except Exception:
+                continue
+        return out
+
     def load_claims(self) -> list[SignedStatement]:
         from hypermind.wire import SignedStatement