hypermind 0.31.1__tar.gz → 0.32.0__tar.gz

{hypermind-0.31.1 → hypermind-0.32.0}/CHANGELOG.md

@@ -16,6 +16,13 @@ changes only on major-version bumps.
 
 _Current trunk._
 
+## [0.32.0] — 2026-07-09
+
+### Added
+- **Persistent shared config** — `hmctl orgs` auto-loads keys from `~/.config/hypermind/env` (then `~/.hypermind/env`, then `./.env`, or `$HYPERMIND_CONFIG`); exported env still wins. Store keys once, never re-export.
+- **Env-backed flags** — every `hmctl orgs` flag also reads an env var (`RELATA_URL`, `OPENAI_BASE_URL`, `HYPERMIND_LLM`, `HYPERMIND_LLM_MODEL`, `HYPERMIND_API_KEY_ENV`, `HYPERMIND_TEMPLATE`), so with the persistent config the commands run **flag-free** (`hmctl orgs ask "…"`).
+- **`hmctl orgs config`** — shows the resolved config paths + which keys are set (masked).
+
 ## [0.31.1] — 2026-07-09
 
 ### Added

{hypermind-0.31.1 → hypermind-0.32.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypermind
-Version: 0.31.1
+Version: 0.32.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
@@ -239,7 +239,15 @@ report.print()        # reputation ranking · citation graph · dispute ledger
 
 ### 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, …).
+**First run in three lines** — store keys once, then commands take *no flags*:
+```bash
+mkdir -p ~/.config/hypermind && cp .env.example ~/.config/hypermind/env  # add your key
+docker compose -f deploy/docker-compose.yml up -d relata                 # backend
+hmctl orgs ask "what limits protein folding?" --live                     # go
+```
+`hmctl orgs` auto-loads `~/.config/hypermind/env` (then `~/.hypermind/env`, then `./.env`); exported env still wins. `hmctl orgs config` shows what's loaded; `hmctl orgs doctor` verifies you're ready.
+
+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, …). Every flag also reads an env var, so the persistent config drives them:
 
 ```bash
 hmctl orgs templates                         # list the presets

{hypermind-0.31.1 → hypermind-0.32.0}/README.md

@@ -151,7 +151,15 @@ report.print()        # reputation ranking · citation graph · dispute ledger
 
 ### 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, …).
+**First run in three lines** — store keys once, then commands take *no flags*:
+```bash
+mkdir -p ~/.config/hypermind && cp .env.example ~/.config/hypermind/env  # add your key
+docker compose -f deploy/docker-compose.yml up -d relata                 # backend
+hmctl orgs ask "what limits protein folding?" --live                     # go
+```
+`hmctl orgs` auto-loads `~/.config/hypermind/env` (then `~/.hypermind/env`, then `./.env`); exported env still wins. `hmctl orgs config` shows what's loaded; `hmctl orgs doctor` verifies you're ready.
+
+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, …). Every flag also reads an env var, so the persistent config drives them:
 
 ```bash
 hmctl orgs templates                         # list the presets

{hypermind-0.31.1 → hypermind-0.32.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypermind"
-version = "0.31.1"
+version = "0.32.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.31.1 → hypermind-0.32.0}/src/hmctl/orgs_cmd.py

@@ -76,18 +76,26 @@ def _require_relata(relata_url: str | None) -> str:
 
 
 def _llm_opts(fn):
-    """Shared LLM/Relata options for the run commands."""
+    """Shared LLM/Relata options — every one also reads an env var (via the
+    persistent config), so with keys stored once the commands need no flags."""
     opts = [
-        click.option("--template", default="university", help="preset org (see `orgs templates`)"),
+        click.option("--template", envvar="HYPERMIND_TEMPLATE", default="university",
+                     help="preset org (see `orgs templates`)  [env: HYPERMIND_TEMPLATE]"),
         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"),
+        click.option("--relata-url", envvar="RELATA_URL", default=None,
+                     help="Relata URL  [env: RELATA_URL]"),
+        click.option("--relata-token", envvar="RELATA_TOKEN", default=None,
+                     help="Relata bearer  [env: RELATA_TOKEN]"),
+        click.option("--llm", envvar="HYPERMIND_LLM", default="openai",
+                     help="openai | anthropic  [env: HYPERMIND_LLM]"),
+        click.option("--llm-model", envvar="HYPERMIND_LLM_MODEL", default=None,
+                     help="model id, e.g. openai/gpt-4o-mini  [env: HYPERMIND_LLM_MODEL]"),
+        click.option("--base-url", envvar="OPENAI_BASE_URL", default=None,
+                     help="LLM base URL (e.g. OpenRouter)  [env: OPENAI_BASE_URL]"),
+        click.option("--api-key-env", envvar="HYPERMIND_API_KEY_ENV", default=None,
+                     help="env var holding the API key  [env: HYPERMIND_API_KEY_ENV]"),
     ]
     for o in reversed(opts):
         fn = o(fn)
@@ -110,9 +118,70 @@ def _run(go, dash):
         return asyncio.run(go())
 
 
+def _config_paths() -> list[str]:
+    """Where hmctl looks for persistent env, highest precedence first."""
+    import os
+
+    paths = []
+    if os.environ.get("HYPERMIND_CONFIG"):
+        paths.append(os.environ["HYPERMIND_CONFIG"])
+    paths += ["~/.config/hypermind/env", "~/.hypermind/env", ".env"]
+    return paths
+
+
+def load_persistent_env() -> list[str]:
+    """Load KEY=VALUE lines from the config files into the environment, without
+    overriding anything already exported (real env wins). Returns the files
+    actually loaded. So keys live once in ``~/.config/hypermind/env`` and every
+    ``hmctl orgs`` run picks them up — no re-exporting each shell."""
+    import os
+    from pathlib import Path
+
+    loaded = []
+    for p in _config_paths():
+        fp = Path(p).expanduser()
+        if not fp.is_file():
+            continue
+        for line in fp.read_text().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            k, _, v = line.partition("=")
+            os.environ.setdefault(k.strip(), v.strip().strip('"').strip("'"))
+        loaded.append(str(fp))
+    return loaded
+
+
 @click.group()
 def orgs() -> None:
     """Run the hypermind.orgs living-simulation engine (no code)."""
+    load_persistent_env()  # ~/.config/hypermind/env → env (exported env still wins)
+
+
+@orgs.command("config")
+def config_cmd() -> None:
+    """Show where persistent keys are read from, and which are set (masked)."""
+    import os
+
+    from rich.console import Console
+
+    console = Console()
+    console.print("[bold]config files[/] (highest precedence first):")
+    for p in _config_paths():
+        from pathlib import Path
+
+        exists = Path(p).expanduser().is_file()
+        console.print(f"  {'[green]✓[/]' if exists else '[grey42]·[/]'} {p}")
+    console.print("\n[bold]keys[/] (after loading):")
+    for k in ("OPENAI_API_KEY", "OPENROUTER_API_KEY", "OPENAI_BASE_URL", "ANTHROPIC_API_KEY",
+              "RELATA_URL", "RELATA_TOKEN"):
+        v = os.environ.get(k)
+        shown = "[grey42]unset[/]" if not v else (
+            f"[green]{v}[/]" if k.endswith(("URL",)) else f"[green]{'*' * 6}{v[-4:]}[/]"
+        )
+        console.print(f"  {k:20s} {shown}")
+    console.print("\nStore keys persistently:  "
+                  "[cyan]mkdir -p ~/.config/hypermind && cp .env ~/.config/hypermind/env[/]")
 
 
 @orgs.command("templates")
@@ -133,10 +202,11 @@ def _relata_health(url: str) -> bool:
 
 
 @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("--relata-url", envvar="RELATA_URL", default=None, help="Relata URL [env: RELATA_URL]")
+@click.option("--relata-token", envvar="RELATA_TOKEN", default=None)
+@click.option("--llm", envvar="HYPERMIND_LLM", default="openai", help="openai | anthropic")
+@click.option("--api-key-env", envvar="HYPERMIND_API_KEY_ENV", default=None,
+              help="env var holding the LLM API key [env: HYPERMIND_API_KEY_ENV]")
 @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)"""

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

{hypermind-0.31.1 → hypermind-0.32.0}/tests/test_cli_orgs.py

@@ -18,6 +18,44 @@ def test_templates_lists_presets() -> None:
     assert "un_security_council" in res.output
 
 
+def test_load_persistent_env_and_exported_wins(monkeypatch, tmp_path) -> None:
+    import os
+
+    cfg = tmp_path / "env"
+    cfg.write_text("# keys\nRELATA_URL=http://cfg:9090\nHM_TEST_KEY=from-file\n")
+    monkeypatch.setenv("HYPERMIND_CONFIG", str(cfg))
+    monkeypatch.delenv("RELATA_URL", raising=False)
+    monkeypatch.setenv("HM_TEST_KEY", "exported")  # exported must win over the file
+    loaded = oc.load_persistent_env()
+    assert str(cfg) in loaded
+    assert os.environ["RELATA_URL"] == "http://cfg:9090"  # filled from config
+    assert os.environ["HM_TEST_KEY"] == "exported"  # not overridden
+
+
+def test_config_command_lists_paths() -> None:
+    res = CliRunner().invoke(main, ["orgs", "config"])
+    assert res.exit_code == 0
+    assert "config files" in res.output
+    assert "~/.config/hypermind/env" in res.output
+
+
+def test_orgs_group_autoloads_config(monkeypatch, tmp_path) -> None:
+    import hypermind.orgs.distributed as hd
+    from hypermind.orgs.distributed.provision import HM_TYPES
+
+    cfg = tmp_path / "env"
+    cfg.write_text("RELATA_URL=http://cfg:9090\nOPENAI_API_KEY=x\n")
+    monkeypatch.setenv("HYPERMIND_CONFIG", str(cfg))
+    monkeypatch.delenv("RELATA_URL", raising=False)
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    monkeypatch.setattr(oc, "_relata_health", lambda url: True)
+    monkeypatch.setattr(hd, "provision_hm_types", lambda *a, **k: {t: "exists" for t in HM_TYPES})
+    # No env exported — doctor must pass purely from the persistent config file.
+    res = CliRunner().invoke(main, ["orgs", "doctor"])
+    assert res.exit_code == 0
+    assert "ready to simulate" 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
@@ -48,9 +86,14 @@ def test_unknown_template_is_clear_error() -> None:
     assert "unknown template" in res.output
 
 
-def test_requires_relata_url(monkeypatch) -> None:
+def test_requires_relata_url(monkeypatch, tmp_path) -> None:
+    # Isolate from every persistent-config source (HOME for ~/.config, cwd for .env).
     monkeypatch.delenv("RELATA_URL", raising=False)
-    res = CliRunner().invoke(main, ["orgs", "simulate", "--topic", "t"])
+    monkeypatch.delenv("HYPERMIND_CONFIG", raising=False)
+    monkeypatch.setenv("HOME", str(tmp_path))
+    runner = CliRunner()
+    with runner.isolated_filesystem():
+        res = runner.invoke(main, ["orgs", "simulate", "--topic", "t"])
     assert res.exit_code != 0
     assert "Relata URL" in res.output