hypermind 0.30.0__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.0 → hypermind-0.31.0}/CHANGELOG.md

@@ -16,6 +16,21 @@ 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
+- **Fancy quality panel with fill animation.** `hmctl orgs ask` now renders the answer + quality rubrics as a colour-graded Rich panel — per-rubric gauges (grounding, **hallucination**, calibration, consensus, …), an overall gauge, and a green/red hallucination callout. On a real terminal the gauges **animate (fill up)** on reveal; piped/CI output renders once. So hallucination and every other metric are now visible clearly, not a plain text list.
+
 ## [0.30.0] — 2026-07-08
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypermind
-Version: 0.30.0
+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.0 → 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.0 → 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.0 → 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.0 → hypermind-0.31.0}/pyproject.toml

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

@@ -176,3 +176,119 @@ class SimDashboard:
         return Panel(
             body, border_style="#00e5ff", title="live simulation", subtitle="hypermind.orgs"
         )
+
+
+# --- fancy quality / answer render (post-run) -----------------------------
+_WORSE = {"hallucination_rate", "dispute_exposure", "calibration_brier"}
+_LABELS = {
+    "provenance_coverage": "provenance",
+    "dispute_exposure": "dispute exposure",
+    "reputation_support": "reputation support",
+    "consensus": "consensus",
+    "abstention_ok": "abstention",
+    "grounding": "grounding",
+    "hallucination_rate": "hallucination",
+    "answer_relevance": "relevance",
+    "context_precision": "context precision",
+    "calibration_brier": "calibration (Brier)",
+    "self_consistency": "self-consistency",
+    "context_recall": "context recall",
+}
+
+
+def _score_colour(good: float) -> str:
+    return "#00ff9c" if good >= 0.8 else "#ffd166" if good >= 0.5 else "#ff5d8f"
+
+
+def _gauge(good: float, width: int = 24) -> Text:
+    filled = int(max(0.0, min(1.0, good)) * width)
+    t = Text()
+    t.append("█" * filled, style=_score_colour(good))
+    t.append("─" * (width - filled), style="grey30")
+    return t
+
+
+def _answer_panel(answer: Any) -> Panel:
+    ans = Text()
+    ans.append(f"{answer.stance.upper()}", style="bold #00e5ff")
+    ans.append(f"   confidence {answer.confidence:.2f}\n\n", style="grey70")
+    reasoning = answer.reasoning or ""
+    ans.append(reasoning[:700] + ("…" if len(reasoning) > 700 else ""), style="white")
+    if answer.contributors:
+        ans.append("\n\ndrew on: ", style="grey54")
+        ans.append(
+            ", ".join(f"{c.label}({c.reputation:.2f})" for c in answer.contributors[:5]),
+            style="grey62",
+        )
+    return Panel(ans, title="🧠 answer", border_style="#00e5ff", padding=(1, 2))
+
+
+def _quality_panel(report: Any, *, reveal: float = 1.0) -> Panel:
+    """Build the quality panel; ``reveal`` in [0,1] scales the gauges for the
+    fill animation (1.0 = final)."""
+    ov = report.overall() or 0.0
+    header = Text()
+    header.append(f"overall {ov * reveal:.2f}/1.00   ", style=f"bold {_score_colour(ov)}")
+    header.append_text(_gauge(ov * reveal))
+
+    grid = Table.grid(padding=(0, 2))
+    grid.add_column(justify="right")
+    grid.add_column()
+    grid.add_column(justify="right")
+    for name, label in _LABELS.items():
+        if name not in report.metrics:
+            continue
+        val = report.metrics[name]
+        good = (1.0 - val) if name in _WORSE else val
+        colour = _score_colour(good)
+        arrow = "↓" if name in _WORSE else "↑"
+        grid.add_row(
+            Text(f"{label} {arrow}", style="grey74"),
+            _gauge(good * reveal, 18),
+            Text(f"{val:.2f}" if reveal >= 1.0 else "", style=f"bold {colour}"),
+        )
+
+    parts: list[Any] = [header, Text(""), grid]
+    if reveal >= 1.0:  # callout + notes appear once the bars have filled
+        halluc = report.metrics.get("hallucination_rate")
+        if halluc is not None:
+            if halluc == 0:
+                parts += [Text(""), Text(
+                    "✓ no hallucination detected — every claim grounded in context",
+                    style="bold #00ff9c")]
+            else:
+                c = Text(f"⚠ {len(report.hallucinated_claims)} unsupported claim(s):",
+                         style="bold #ff5d8f")
+                for claim in report.hallucinated_claims[:4]:
+                    c.append(f"\n    • {claim}", style="#ff5d8f")
+                parts += [Text(""), c]
+        for n in report.notes:
+            parts.append(Text(f"· {n}", style="grey42"))
+    return Panel(
+        Group(*parts),
+        title="📊 answer quality",
+        border_style=_score_colour(ov),
+        subtitle="hypermind.orgs · quality rubrics",
+        padding=(1, 2),
+    )
+
+
+def render_answer_quality(
+    console: Console, answer: Any, report: Any = None, *, animate: bool = True
+) -> None:
+    """Print the answer + a colourful quality panel. On a real terminal the
+    gauges **fill up** with a short reveal animation; piped/CI output renders
+    the final frame once (deterministic, no sleeps)."""
+    console.print(_answer_panel(answer))
+    if report is None:
+        return
+    if animate and console.is_terminal:
+        import time
+
+        frames = 22
+        with Live(console=console, refresh_per_second=60) as live:
+            for f in range(frames + 1):
+                live.update(_quality_panel(report, reveal=f / frames))
+                time.sleep(0.022)
+    else:
+        console.print(_quality_panel(report, reveal=1.0))

{hypermind-0.30.0 → 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>"
@@ -256,9 +315,11 @@ def ask_cmd(
             return answer, report
 
     answer, report = _run(go, dash)
-    answer.print()
-    if report is not None:
-        report.print()
+    from rich.console import Console
+
+    from hmctl.dashboard import render_answer_quality
+
+    render_answer_quality(Console(), answer, report)
 
 
 @orgs.command("distributed")

{hypermind-0.30.0 → 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.0"
+__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.0 → 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"]
@@ -48,13 +70,19 @@ class _Report:
 
 
 class _Answer:
-    def print(self):
-        print("ANSWER-PRINTED")
+    stance = "supports"
+    confidence = 0.88
+    reasoning = "ANSWER-PRINTED reasoning text"
+    contributors: ClassVar = []
 
 
 class _Quality:
-    def print(self):
-        print("QUALITY-PRINTED")
+    metrics: ClassVar = {"grounding": 1.0, "hallucination_rate": 0.0}
+    hallucinated_claims: ClassVar = []
+    notes: ClassVar = ["QUALITY-PRINTED note"]
+
+    def overall(self):
+        return 0.97
 
 
 class _FakeSim:

{hypermind-0.30.0 → hypermind-0.31.0}/tests/test_dashboard.py

@@ -3,10 +3,11 @@
 from __future__ import annotations
 
 import io
+import types
 
 from rich.console import Console
 
-from hmctl.dashboard import SimDashboard, _spark
+from hmctl.dashboard import SimDashboard, _spark, render_answer_quality
 
 
 def _dash() -> SimDashboard:
@@ -54,3 +55,42 @@ def test_spark_scales_and_handles_empty():
     assert str(_spark([]))  # no crash on empty
     s = _spark([0, 1, 2, 3, 4, 8])
     assert len(str(s)) >= 6  # one glyph per value
+
+
+def _answer(reasoning="an answer"):
+    return types.SimpleNamespace(
+        stance="supports", confidence=0.88, reasoning=reasoning,
+        contributors=[types.SimpleNamespace(label="a/O#1", reputation=0.9)],
+    )
+
+
+def _report(halluc, claims=(), notes=()):
+    return types.SimpleNamespace(
+        metrics={"grounding": 1.0, "hallucination_rate": halluc, "consensus": 0.9},
+        hallucinated_claims=list(claims), notes=list(notes), overall=lambda: 0.95,
+    )
+
+
+def test_quality_panel_clean_answer():
+    con = Console(file=io.StringIO(), width=100)
+    render_answer_quality(con, _answer(), _report(0.0, notes=["x: SKIPPED"]))
+    out = con.file.getvalue()
+    assert "answer quality" in out
+    assert "no hallucination" in out
+    assert "hallucination" in out and "grounding" in out
+
+
+def test_quality_panel_flags_hallucination():
+    con = Console(file=io.StringIO(), width=100)
+    render_answer_quality(con, _answer(), _report(1.0, claims=["fabricated stat"]))
+    out = con.file.getvalue()
+    assert "unsupported claim" in out
+    assert "fabricated stat" in out
+
+
+def test_answer_only_without_report():
+    con = Console(file=io.StringIO(), width=100)
+    render_answer_quality(con, _answer("just the answer"), None)
+    out = con.file.getvalue()
+    assert "answer" in out
+    assert "answer quality" not in out  # no report → no quality panel