hypermind 0.30.1__tar.gz → 0.31.0__tar.gz

hypermind-0.31.0/.env.example

@@ -0,0 +1,26 @@
+# hypermind — environment for the orgs engine / hmctl orgs / distributed runs.
+# Copy to .env and fill in. `hmctl orgs doctor` verifies these are set correctly.
+
+# --- LLM (pick one provider) ------------------------------------------------
+# OpenAI-compatible (OpenAI, OpenRouter, local gateways, …)
+OPENAI_API_KEY=
+# Optional: point at an OpenAI-compatible gateway (e.g. OpenRouter).
+# OPENAI_BASE_URL=https://openrouter.ai/api/v1
+# If your key lives in a different var, pass --api-key-env to hmctl (e.g. OPENROUTER_API_KEY).
+# OPENROUTER_API_KEY=
+
+# Anthropic (only if you use --llm anthropic)
+# ANTHROPIC_API_KEY=
+
+# --- Relata (shared state / source of truth) --------------------------------
+RELATA_URL=http://localhost:9090
+# Bearer token if the server requires auth (lite/dev mode needs none).
+# RELATA_TOKEN=
+
+# Start Relata so the orgs ledger types are writable by the unauthenticated
+# dev principal (lite mode). The Hm* types themselves are auto-registered by
+# `hmctl orgs` / the distributed master; this env grants access at boot:
+#
+#   RELATA_ORG_MODE=lite \
+#   RELATA_ACL_GRANT="HmClaim:read+write,HmDispute:read+write,HmReputation:read+write,HmTranscript:read+write" \
+#     relata serve

{hypermind-0.30.1 → hypermind-0.31.0}/CHANGELOG.md

@@ -16,6 +16,16 @@ changes only on major-version bumps.
 
 _Current trunk._
 
+## [0.31.0] — 2026-07-09
+
+### Added
+- **`hmctl orgs doctor`** — one-command preflight for adoption: checks the LLM API key, Relata reachability, and that the `Hm*` ledger types are writable, with ✓/✗ and a fix hint per row. Exit 0 only when ready.
+- **`.env.example`** — every env var the orgs engine needs, in one place.
+- **Deploy & scale docs** — README section: set env → `doctor` → start Relata (with the `RELATA_ACL_GRANT` boot line) → single-host run → cluster (master/worker) commands.
+
+### Fixed
+- Example prerequisites pointed at a non-existent `docker compose … relata` service; now show the real `relata serve` command with the ACL grant.
+
 ## [0.30.1] — 2026-07-08
 
 ### Added

{hypermind-0.30.1 → hypermind-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypermind
-Version: 0.30.1
+Version: 0.31.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,7 +237,47 @@ 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 "…"`.
+### No-code CLI — `hmctl orgs`
+
+Run the whole engine from the shell (no Python). `--live` shows an animated, colourful dashboard; `ask` prints a quality panel with per-rubric gauges (grounding, **hallucination**, calibration, …).
+
+```bash
+hmctl orgs templates                         # list the presets
+hmctl orgs simulate --template university --members 24 --rounds 6 \
+    --topic "what limits protein folding?" --live      # animated dashboard + report
+hmctl orgs ask "what limits protein folding?" --template university --live
+                                             # study → ask → fancy quality panel
+hmctl orgs distributed --template university --members 10000 --workers 8 \
+    --topic "…"                              # sharded across workers, merged report
+```
+
+Common flags: `--relata-url` (or `$RELATA_URL`), `--llm openai|anthropic`, `--llm-model`, `--base-url`, `--api-key-env`, `--html report.html`. Full options: `hmctl orgs <cmd> --help`.
+
+### Deploy & scale (single host → cluster)
+
+**1. Set env** — copy `.env.example` → `.env` (LLM key + `RELATA_URL`), then preflight:
+```bash
+hmctl orgs doctor          # ✓/✗ for LLM key · Relata reachable · Hm* types writable
+```
+
+**2. Start Relata** (lite/dev; the `Hm*` types are auto-registered by the SDK, this grants the dev principal access at boot):
+```bash
+RELATA_ORG_MODE=lite \
+RELATA_ACL_GRANT="HmClaim:read+write,HmDispute:read+write,HmReputation:read+write,HmTranscript:read+write" \
+  relata serve            # → http://localhost:9090
+```
+
+**3. Run** — single host: `hmctl orgs simulate … --live`. Across a **cluster** (Locust-style master/worker; all share one Relata):
+```bash
+# master host — shards the swarm, provisions Relata, reassigns failed shards
+python -m hypermind.orgs.distributed master --template university \
+    --members 10000 --rounds 8 --expected-workers 4 \
+    --host 0.0.0.0 --port 8765 --relata-url http://<relata-host>:9090
+
+# each worker host — dials the master, runs its shard (needs the same LLM env)
+python -m hypermind.orgs.distributed worker \
+    --master-host <master-ip> --port 8765 --capacity 2500
+```
 
 Worked example: [`examples/org_university.py`](examples/org_university.py). Discover all presets via `hypermind.orgs.templates.list_templates()`.
 

{hypermind-0.30.1 → hypermind-0.31.0}/README.md

@@ -149,7 +149,47 @@ 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 "…"`.
+### No-code CLI — `hmctl orgs`
+
+Run the whole engine from the shell (no Python). `--live` shows an animated, colourful dashboard; `ask` prints a quality panel with per-rubric gauges (grounding, **hallucination**, calibration, …).
+
+```bash
+hmctl orgs templates                         # list the presets
+hmctl orgs simulate --template university --members 24 --rounds 6 \
+    --topic "what limits protein folding?" --live      # animated dashboard + report
+hmctl orgs ask "what limits protein folding?" --template university --live
+                                             # study → ask → fancy quality panel
+hmctl orgs distributed --template university --members 10000 --workers 8 \
+    --topic "…"                              # sharded across workers, merged report
+```
+
+Common flags: `--relata-url` (or `$RELATA_URL`), `--llm openai|anthropic`, `--llm-model`, `--base-url`, `--api-key-env`, `--html report.html`. Full options: `hmctl orgs <cmd> --help`.
+
+### Deploy & scale (single host → cluster)
+
+**1. Set env** — copy `.env.example` → `.env` (LLM key + `RELATA_URL`), then preflight:
+```bash
+hmctl orgs doctor          # ✓/✗ for LLM key · Relata reachable · Hm* types writable
+```
+
+**2. Start Relata** (lite/dev; the `Hm*` types are auto-registered by the SDK, this grants the dev principal access at boot):
+```bash
+RELATA_ORG_MODE=lite \
+RELATA_ACL_GRANT="HmClaim:read+write,HmDispute:read+write,HmReputation:read+write,HmTranscript:read+write" \
+  relata serve            # → http://localhost:9090
+```
+
+**3. Run** — single host: `hmctl orgs simulate … --live`. Across a **cluster** (Locust-style master/worker; all share one Relata):
+```bash
+# master host — shards the swarm, provisions Relata, reassigns failed shards
+python -m hypermind.orgs.distributed master --template university \
+    --members 10000 --rounds 8 --expected-workers 4 \
+    --host 0.0.0.0 --port 8765 --relata-url http://<relata-host>:9090
+
+# each worker host — dials the master, runs its shard (needs the same LLM env)
+python -m hypermind.orgs.distributed worker \
+    --master-host <master-ip> --port 8765 --capacity 2500
+```
 
 Worked example: [`examples/org_university.py`](examples/org_university.py). Discover all presets via `hypermind.orgs.templates.list_templates()`.
 

{hypermind-0.30.1 → hypermind-0.31.0}/examples/org_distributed.py

@@ -22,7 +22,9 @@ multi-machine. For true multi-machine, use the CLI instead::
         --master-host <master-ip> --port 8765 --capacity 2500
 
 PREREQUISITES
-  * A running Relata instance:   docker compose -f deploy/docker-compose.yml up -d relata
+  * A running Relata (lite/dev):  RELATA_ORG_MODE=lite \
+      RELATA_ACL_GRANT="HmClaim:read+write,HmDispute:read+write,HmReputation:read+write,HmTranscript:read+write" \
+      relata serve         # Hm* types are auto-registered by the SDK; verify with `hmctl orgs doctor`
   * export RELATA_URL=http://localhost:9090   RELATA_TOKEN=...
   * export OPENAI_API_KEY=...   (workers build their own client from env)
 

{hypermind-0.30.1 → hypermind-0.31.0}/examples/org_university.py

@@ -13,7 +13,9 @@ 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
+  * A running Relata (lite/dev):  RELATA_ORG_MODE=lite \
+      RELATA_ACL_GRANT="HmClaim:read+write,HmDispute:read+write,HmReputation:read+write,HmTranscript:read+write" \
+      relata serve         # Hm* types are auto-registered by the SDK; verify with `hmctl orgs doctor`
   * export RELATA_URL=http://localhost:9090   RELATA_TOKEN=...
   * export ANTHROPIC_API_KEY=...   (or use llm="openai" + OPENAI_API_KEY)
 

{hypermind-0.30.1 → hypermind-0.31.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypermind"
-version = "0.30.1"
+version = "0.31.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.30.1 → hypermind-0.31.0}/src/hmctl/orgs_cmd.py

@@ -122,6 +122,65 @@ def templates_cmd() -> None:
         click.echo(name)
 
 
+def _relata_health(url: str) -> bool:
+    import urllib.request
+
+    try:
+        with urllib.request.urlopen(f"{url.rstrip('/')}/health", timeout=4) as r:
+            return 200 <= r.status < 300
+    except Exception:
+        return False
+
+
+@orgs.command("doctor")
+@click.option("--relata-url", default=None, help="Relata URL (default: $RELATA_URL)")
+@click.option("--relata-token", default=None)
+@click.option("--llm", default="openai", help="openai | anthropic")
+@click.option("--api-key-env", default=None, help="env var holding the LLM API key")
+@click.option("--namespace", default="hmctl-doctor", help="namespace to test provisioning against")
+def doctor_cmd(relata_url, relata_token, llm, api_key_env, namespace) -> None:
+    """Preflight: is everything set up to run a simulation? (env, Relata, types)"""
+    import os
+
+    from rich.console import Console
+    from rich.table import Table
+
+    console = Console()
+    checks: list[tuple[str, bool, str]] = []
+
+    key_env = api_key_env or ("OPENAI_API_KEY" if llm == "openai" else "ANTHROPIC_API_KEY")
+    checks.append((f"LLM API key (${key_env})", bool(os.environ.get(key_env)),
+                   f"export {key_env}=… (or pass --api-key-env / --llm)"))
+
+    url = relata_url or os.environ.get("RELATA_URL")
+    reachable = bool(url) and _relata_health(url)
+    checks.append(("Relata reachable", reachable,
+                   "set --relata-url / $RELATA_URL and start Relata (see `hmctl orgs` docs)"))
+
+    if reachable:
+        from hypermind.orgs.distributed import provision_hm_types
+
+        res = provision_hm_types(url, namespace=namespace, token=relata_token)
+        ok = all(v in ("registered", "exists") for v in res.values())
+        detail = "" if ok else " · ".join(f"{k}:{v}" for k, v in res.items())
+        checks.append(("Hm* ledger types writable", ok,
+                       f"boot Relata with RELATA_ACL_GRANT=HmClaim:read+write,HmDispute:read+write,"
+                       f"HmReputation:read+write,HmTranscript:read+write  {detail}"))
+
+    table = Table(title="hmctl orgs doctor", show_lines=False)
+    table.add_column("check")
+    table.add_column("status", justify="center")
+    table.add_column("fix", style="grey62")
+    for name, ok, fix in checks:
+        table.add_row(name, "[green]✓[/]" if ok else "[red]✗[/]", "" if ok else fix)
+    console.print(table)
+
+    ready = all(ok for _n, ok, _f in checks)
+    console.print("[bold green]✓ ready to simulate[/]" if ready
+                  else "[bold red]✗ not ready[/] — fix the ✗ rows above")
+    raise SystemExit(0 if ready else 1)
+
+
 def _write_html(report: Any, path: str) -> None:
     rows = "".join(
         f"<tr><td>{s.reputation:.2f}</td><td>{_html.escape(s.label)}</td>"

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

{hypermind-0.30.1 → hypermind-0.31.0}/tests/test_cli_orgs.py

@@ -18,6 +18,28 @@ def test_templates_lists_presets() -> None:
     assert "un_security_council" in res.output
 
 
+def test_doctor_ready_when_all_pass(monkeypatch) -> None:
+    import hypermind.orgs.distributed as hd
+    from hypermind.orgs.distributed.provision import HM_TYPES
+
+    monkeypatch.setenv("OPENAI_API_KEY", "x")
+    monkeypatch.setenv("RELATA_URL", "http://fake:9090")
+    monkeypatch.setattr(oc, "_relata_health", lambda url: True)
+    monkeypatch.setattr(hd, "provision_hm_types", lambda *a, **k: {t: "exists" for t in HM_TYPES})
+    res = CliRunner().invoke(main, ["orgs", "doctor"])
+    assert res.exit_code == 0
+    assert "ready to simulate" in res.output
+
+
+def test_doctor_flags_missing_key_and_relata(monkeypatch) -> None:
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    monkeypatch.delenv("RELATA_URL", raising=False)
+    monkeypatch.setattr(oc, "_relata_health", lambda url: False)
+    res = CliRunner().invoke(main, ["orgs", "doctor"])
+    assert res.exit_code == 1
+    assert "not ready" in res.output
+
+
 def test_unknown_template_is_clear_error() -> None:
     res = CliRunner().invoke(
         main, ["orgs", "simulate", "--template", "nope", "--topic", "t", "--relata-url", "http://x"]