hypermind 1.4.3__tar.gz → 1.4.4__tar.gz

{hypermind-1.4.3 → hypermind-1.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypermind
-Version: 1.4.3
+Version: 1.4.4
 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

{hypermind-1.4.3 → hypermind-1.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypermind"
-version = "1.4.3"
+version = "1.4.4"
 description = "Federated agent intelligence — reference SDK for the HyperMind SCITT contested-claims profile"
 readme = "README.md"
 requires-python = ">=3.11,<3.14"

{hypermind-1.4.3 → hypermind-1.4.4}/src/hmctl/cli.py

@@ -459,6 +459,102 @@ def _doctor_check_clock() -> None:
         click.echo(f"ntp_offset_ms     : {ntp_note}")
 
 
+@main.command("status")
+def status_cmd() -> None:
+    """Show what's configured, what's degraded, and how to fix it."""
+    import os as _os
+
+    from rich.console import Console
+    from rich.table import Table
+    from rich import box
+
+    console = Console()
+
+    env_file = _os.path.expanduser("~/.hypermind/env")
+    has_env_file = _os.path.exists(env_file)
+
+    # Load env file so vars set there appear in checks
+    if has_env_file:
+        for line in open(env_file).read().splitlines():
+            line = line.strip()
+            if not line or line.startswith("#") or "=" not in line:
+                continue
+            k, _, v = line.partition("=")
+            k = k.strip()
+            if k and k not in _os.environ:
+                _os.environ[k] = v.strip()
+
+    relata_url = _os.environ.get("RELATA_URL", "")
+    otel_ep = _os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "")
+    db_path = _os.environ.get("HYPERMIND_DB", "")
+    openai_key = bool(_os.environ.get("OPENAI_API_KEY"))
+    anthropic_key = bool(_os.environ.get("ANTHROPIC_API_KEY"))
+    base_url = _os.environ.get("OPENAI_BASE_URL", "")
+    llm_model = _os.environ.get("HYPERMIND_LLM_MODEL", "")
+
+    # Detect LLM
+    if base_url or openai_key:
+        llm_label = llm_model or "gpt-4o (default)"
+        if base_url:
+            llm_label += f"  via {base_url}"
+        llm_ok, llm_note, llm_fix = True, llm_label, ""
+    elif anthropic_key:
+        llm_ok, llm_note, llm_fix = True, llm_model or "claude-3-5-sonnet", ""
+    else:
+        llm_ok = False
+        llm_note = "No LLM key — hm_ask returns deterministic answers; research won't run"
+        llm_fix = (
+            "Add to ~/.hypermind/env:\n"
+            "  OPENAI_API_KEY=sk-…              # OpenAI / OpenRouter\n"
+            "  HYPERMIND_LLM_MODEL=gpt-4o       # required for OpenRouter\n"
+            "  OPENAI_BASE_URL=https://…        # optional proxy/local\n"
+            "  ANTHROPIC_API_KEY=sk-ant-…       # or use Anthropic direct\n"
+            "  # Ollama (no key): OPENAI_BASE_URL=http://localhost:11434/v1"
+        )
+
+    rows = [
+        # (feature, ok, detail, fix)
+        ("env_file", has_env_file,
+         "~/.hypermind/env loaded" if has_env_file else "~/.hypermind/env not found — API keys must be exported every session",
+         "touch ~/.hypermind/env  # one KEY=VALUE per line"),
+        ("llm", llm_ok, llm_note, llm_fix),
+        ("relata", bool(relata_url),
+         relata_url if relata_url else "No durable ledger — claims are in-process only, lost on restart; hm_related falls back to keyword scan",
+         "1. bash deploy/relata-serve.sh\n2. Add RELATA_URL=http://localhost:5432 to ~/.hypermind/env\n3. Restart hmctl mcp serve"),
+        ("otel", bool(otel_ep),
+         otel_ep if otel_ep else "No OTLP endpoint — audit trail is local-only, not shipped to your observability stack",
+         "Add OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 to ~/.hypermind/env\n(Jaeger / Grafana Tempo / Honeycomb / Datadog all accept OTLP)"),
+        ("sqlite_cache", bool(db_path),
+         db_path if db_path else "No local DB — in-process only; all claims reset on server restart",
+         "Add HYPERMIND_DB=~/.hypermind/cache.db to ~/.hypermind/env"),
+    ]
+
+    table = Table(title=f"hmctl status — HyperMind {__version__}", box=box.ROUNDED, show_lines=True)
+    table.add_column("Feature", style="bold")
+    table.add_column("Status", width=8)
+    table.add_column("Detail / Next step")
+
+    issues: list[tuple[str, str]] = []
+    for feature, ok, detail, fix in rows:
+        icon = "[green]✓ ok[/green]" if ok else "[yellow]✗ off[/yellow]"
+        cell = detail
+        if not ok and fix:
+            issues.append((feature, fix))
+            cell = f"[dim]{detail}[/dim]"
+        table.add_row(feature, icon, cell)
+
+    console.print(table)
+
+    if issues:
+        console.print("\n[bold]Next steps to activate missing features:[/bold]")
+        for feature, fix in issues:
+            console.print(f"\n  [cyan]{feature}[/cyan]")
+            for line in fix.splitlines():
+                console.print(f"    {line}")
+    else:
+        console.print("\n[green]All features active.[/green]")
+
+
 @main.command("conformance")
 def conformance() -> None:
     """Print the conformance contract (CLI is the authority's API)."""

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

{hypermind-1.4.3 → hypermind-1.4.4}/src/hypermind/integrations/mcp_tools.py

@@ -1408,6 +1408,194 @@ def register_hypermind_tools(
         parameters_schema=_org_schema,
         handler=hm_org_roster,
     )
+    async def hm_status(_params: dict[str, Any]) -> Any:
+        """Return a full picture of what's configured, what's degraded, and how to fix it."""
+        import os as _os
+
+        from hypermind import __version__
+
+        relata_url = _os.environ.get("RELATA_URL", "")
+        otel_ep = _os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT", "")
+        db_path = _os.environ.get("HYPERMIND_DB", "")
+        llm_model = _os.environ.get("HYPERMIND_LLM_MODEL", "")
+        openai_key = bool(_os.environ.get("OPENAI_API_KEY"))
+        anthropic_key = bool(_os.environ.get("ANTHROPIC_API_KEY"))
+        base_url = _os.environ.get("OPENAI_BASE_URL", "")
+        env_file = _os.path.expanduser("~/.hypermind/env")
+        has_env_file = _os.path.exists(env_file)
+        responder_model = getattr(client._responder, "model", None)
+
+        # ---- feature blocks ----
+        features: list[dict] = []
+
+        # LLM
+        if responder_model:
+            features.append({
+                "feature": "llm",
+                "status": "ok",
+                "detail": f"{responder_model}" + (f" via {base_url}" if base_url else ""),
+                "affects": ["hm_ask", "hm_research_start", "hm_learn"],
+            })
+        else:
+            features.append({
+                "feature": "llm",
+                "status": "degraded",
+                "detail": "No LLM key detected — hm_ask returns deterministic reputation-only answers.",
+                "affects": ["hm_ask", "hm_research_start", "hm_learn"],
+                "fix": (
+                    "Add to ~/.hypermind/env:\n"
+                    "  # OpenAI / OpenRouter / vLLM / Ollama (OpenAI-compatible):\n"
+                    "  OPENAI_API_KEY=sk-…\n"
+                    "  OPENAI_BASE_URL=https://openrouter.ai/api/v1   # optional, for proxies\n"
+                    "  HYPERMIND_LLM_MODEL=gpt-4o                     # required for OpenRouter\n"
+                    "  # Anthropic direct:\n"
+                    "  ANTHROPIC_API_KEY=sk-ant-…\n"
+                    "  # Ollama (local, no key needed):\n"
+                    "  OPENAI_BASE_URL=http://localhost:11434/v1\n"
+                    "  HYPERMIND_LLM_MODEL=llama3.1"
+                ),
+            })
+
+        # Relata
+        if relata_url:
+            features.append({
+                "feature": "relata",
+                "status": "ok",
+                "detail": relata_url,
+                "affects": ["hm_retrieve", "hm_related", "hm_research_start", "hm_learn"],
+            })
+        else:
+            features.append({
+                "feature": "relata",
+                "status": "degraded",
+                "detail": (
+                    "No durable ledger — claims are in-process only (lost on restart). "
+                    "hm_retrieve uses lexical scan; hm_related cannot traverse the citation graph."
+                ),
+                "affects": ["hm_retrieve", "hm_related", "hm_research_start", "hm_learn"],
+                "fix": (
+                    "1. Deploy RelataDB:  bash deploy/relata-serve.sh\n"
+                    "2. Add to ~/.hypermind/env:\n"
+                    "   RELATA_URL=http://localhost:5432\n"
+                    "3. Restart hmctl mcp serve"
+                ),
+            })
+
+        # OTEL
+        if otel_ep:
+            features.append({
+                "feature": "otel",
+                "status": "ok",
+                "detail": otel_ep,
+                "affects": ["all tool calls → spans exported"],
+            })
+        else:
+            features.append({
+                "feature": "otel",
+                "status": "off",
+                "detail": "No OTLP endpoint — tool-call audit trail is recorded locally only.",
+                "affects": ["observability"],
+                "fix": (
+                    "Add to ~/.hypermind/env:\n"
+                    "  OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317\n"
+                    "Compatible with Jaeger, Grafana Tempo, Honeycomb, Datadog."
+                ),
+            })
+
+        # SQLite local cache
+        if db_path:
+            features.append({
+                "feature": "sqlite_cache",
+                "status": "ok",
+                "detail": db_path,
+                "affects": ["hm_retrieve (persistent across restarts without Relata)"],
+            })
+        else:
+            features.append({
+                "feature": "sqlite_cache",
+                "status": "off",
+                "detail": "In-process memory only — claims reset on server restart.",
+                "affects": ["hm_retrieve"],
+                "fix": "Add HYPERMIND_DB=~/.hypermind/cache.db to ~/.hypermind/env",
+            })
+
+        # Write mode
+        if writable:
+            features.append({
+                "feature": "write_mode",
+                "status": "ok",
+                "detail": "hm_publish_claim is active.",
+                "affects": ["hm_publish_claim"],
+            })
+        else:
+            features.append({
+                "feature": "write_mode",
+                "status": "off",
+                "detail": "Read-only mode — hm_publish_claim is not registered.",
+                "affects": ["hm_publish_claim"],
+                "fix": 'Restart with --write flag:  hmctl mcp serve --write',
+            })
+
+        # Config file
+        config_status = {
+            "feature": "env_file",
+            "status": "ok" if has_env_file else "missing",
+            "detail": "~/.hypermind/env loaded" if has_env_file else "~/.hypermind/env not found",
+        }
+        if not has_env_file:
+            config_status["fix"] = (
+                "touch ~/.hypermind/env  # then add KEY=VALUE lines, one per line\n"
+                "# Example:\n"
+                "OPENAI_API_KEY=sk-…\n"
+                "HYPERMIND_LLM_MODEL=gpt-4o\n"
+                "RELATA_URL=http://localhost:5432"
+            )
+        features.append(config_status)
+
+        # Recent errors from recorder
+        rec = client._primary._world.recorder
+        recent = getattr(rec, "_events", [])
+        errors = [
+            {"event": e.get("event_type"), "error": e.get("error"), "ts": e.get("ts")}
+            for e in (recent[-200:] if hasattr(recent, "__getitem__") else [])
+            if e.get("error") or e.get("status") == "error"
+        ]
+
+        degraded = [f for f in features if f["status"] in ("degraded", "off", "missing")]
+        next_steps = []
+        for f in degraded:
+            fix = f.get("fix")
+            if fix:
+                next_steps.append({"feature": f["feature"], "action": fix})
+
+        return {
+            "version": __version__,
+            "mode": "read-write" if writable else "read-only",
+            "features": features,
+            "degraded_count": len(degraded),
+            "next_steps": next_steps,
+            "recent_errors": errors[-10:],
+            "summary": (
+                "All features active."
+                if not degraded
+                else f"{len(degraded)} feature(s) degraded or off: "
+                + ", ".join(f['feature'] for f in degraded)
+                + ". See next_steps for fix instructions."
+            ),
+        }
+
+    server.register_tool(
+        "hm_status",
+        description=(
+            "Show what's configured, what's degraded, and exactly how to fix it. "
+            "Returns per-feature status (llm, relata, otel, sqlite_cache, write_mode, env_file), "
+            "which tools each feature affects, recent errors, and step-by-step next_steps. "
+            "Call this first if anything seems wrong or missing."
+        ),
+        parameters_schema={"type": "object", "properties": {}},
+        handler=hm_status,
+    )
+
     server.register_tool(
         "hm_eval",
         description=(

{hypermind-1.4.3 → hypermind-1.4.4}/tests/integrations/test_mcp_tools.py

@@ -264,3 +264,24 @@ async def test_register_on_bare_server():
         assert _EXPECTED_TOOLS <= set(server.tools)
     finally:
         await client.close()
+
+
+@pytest.mark.asyncio
+async def test_hm_status_shape():
+    server, client = build_mcp_server(writable=True)
+    try:
+        out = await _handler(server, "hm_status")({})
+        assert "version" in out and "features" in out and "summary" in out
+        assert "next_steps" in out and "degraded_count" in out and "recent_errors" in out
+        features_by_name = {f["feature"]: f for f in out["features"]}
+        assert "llm" in features_by_name
+        assert "relata" in features_by_name
+        assert "otel" in features_by_name
+        assert "write_mode" in features_by_name
+        assert features_by_name["write_mode"]["status"] == "ok"
+        for f in out["features"]:
+            assert "status" in f and "detail" in f
+            if f["status"] in ("degraded", "off", "missing"):
+                assert "fix" in f, f"degraded feature {f['feature']} missing fix instructions"
+    finally:
+        await client.close()