Add kit_health.py -- the check that proves the kit works

Built 2026-08-01 and never uploaded. It verifies every part of the kit on three axes -- PRESENT (exists on disk), LOADS (opens/imports/answers), ANSWERS (produces a real result) -- because a weight file that exists but will not load, and a server that listens but returns nothing, both report "fine" to any check that stops at PRESENT.

It caught a private memory file staged for upload before it left the machine, and it is what verified the kit works from a clean directory with none of the author's environment around it.

kit_health.py

@@ -0,0 +1,276 @@
+#!/usr/bin/env python3
+"""KIT HEALTH -- every part of this kit, checked in threes.
+
+Six mechanisms in this project were once found doing nothing while reporting
+success, and not one of them threw an error. Looked at together they always
+failed in one of exactly three places:
+
+    PRESENT   the thing exists on disk
+    LOADS     it can actually be opened / imported / reached
+    ANSWERS   it produces a real result when asked
+
+A weight file that exists but will not load is dead. A server that listens but
+returns nothing is dead. Both report "fine" to any check that stops at PRESENT,
+which is why this checks all three and treats two-of-three as failure.
+
+  python kit_health.py           full report
+  python kit_health.py --quiet   only what is broken
+
+Exit code 0 when everything is alive, 1 otherwise -- so it can gate a release.
+"""
+from __future__ import annotations
+
+import json
+import os
+import socket
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+except Exception:
+    pass
+
+ROOT = Path(__file__).resolve().parent
+QUIET = "--quiet" in sys.argv
+PORT = int(os.getenv("COSMOS_KIT_PORT", "11501"))
+HOST = f"http://127.0.0.1:{PORT}"
+
+OK, DEAD, WARN = "OK", "DEAD", "warn"
+
+
+# ── probes ──────────────────────────────────────────────────────────────────
+def _port_open(port: int, timeout: float = 2.0) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.settimeout(timeout)
+        return s.connect_ex(("127.0.0.1", port)) == 0
+
+
+def _get(path: str, timeout: float = 6.0):
+    try:
+        with urllib.request.urlopen(HOST + path, timeout=timeout) as r:
+            return json.loads(r.read() or b"{}")
+    except Exception:
+        return None
+
+
+def _post(path: str, payload: dict, timeout: float = 90.0):
+    try:
+        req = urllib.request.Request(
+            HOST + path,
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+        )
+        with urllib.request.urlopen(req, timeout=timeout) as r:
+            return json.loads(r.read() or b"{}")
+    except Exception:
+        return None
+
+
+# ── the checks ──────────────────────────────────────────────────────────────
+def check_python():
+    v = sys.version_info
+    present = OK if v >= (3, 9) else DEAD
+    try:
+        import torch  # noqa: F401
+        loads = OK
+        detail = f"python {v.major}.{v.minor}.{v.micro}, torch {torch.__version__}"
+    except Exception as e:
+        return present, DEAD, DEAD, f"torch missing ({type(e).__name__}) -- pip install torch"
+    try:
+        import torch
+        t = torch.ones(4, 4) @ torch.ones(4, 4)
+        answers = OK if float(t.sum()) == 64.0 else DEAD
+    except Exception as e:
+        answers, detail = DEAD, f"torch cannot multiply: {type(e).__name__}"
+    return present, loads, answers, detail
+
+
+def check_weight(name: str, filename: str):
+    p = ROOT / "weights" / filename
+    if not p.exists():
+        return DEAD, DEAD, DEAD, f"weights/{filename} is missing"
+    size = p.stat().st_size
+    try:
+        import torch
+        ck = torch.load(p, map_location="cpu", weights_only=False)
+    except Exception as e:
+        return OK, DEAD, DEAD, f"{size/1e6:.1f} MB but will not load: {type(e).__name__}"
+    sd = ck.get("model") or ck.get("state_dict") or ck if isinstance(ck, dict) else {}
+    n = 0
+    try:
+        n = sum(int(v.numel()) for v in sd.values() if hasattr(v, "numel"))
+    except Exception:
+        pass
+    if not n:
+        return OK, OK, DEAD, f"{size/1e6:.1f} MB, loads, but holds no tensors"
+    extra = ""
+    if isinstance(ck, dict):
+        step = ck.get("total_steps") or ck.get("step")
+        val = ck.get("val") or ck.get("val_loss")
+        bits = [b for b in (f"step {step:,}" if isinstance(step, int) else None,
+                            f"val {val:.5f}" if isinstance(val, float) else None) if b]
+        extra = ("  " + ", ".join(bits)) if bits else ""
+    return OK, OK, OK, f"{n:,} params, {size/1e6:.1f} MB{extra}"
+
+
+def check_server():
+    present = OK if (ROOT / "serving" / "cosmos_serve.py").exists() else DEAD
+    if present == DEAD:
+        return present, DEAD, DEAD, "serving/cosmos_serve.py is missing"
+    if not _port_open(PORT):
+        return present, DEAD, DEAD, f"nothing listening on {PORT} -- menu option 3 starts it"
+    tags = _get("/api/tags")
+    if tags is None:
+        return present, DEAD, DEAD, f"port {PORT} is open but /api/tags does not answer"
+    names = [m.get("name", "") for m in tags.get("models", [])]
+    hers = [n for n in names if n.startswith(("cosmos-phos", "cosmos-cst", "cosmos-spark"))]
+    if not hers:
+        return present, OK, DEAD, f"{len(names)} models served, none of them hers"
+    return present, OK, OK, f"{len(hers)} of hers served: {', '.join(sorted(hers))}"
+
+
+def check_voice():
+    """The one that matters: does she actually say anything back?"""
+    if not _port_open(PORT):
+        return DEAD, DEAD, DEAD, "server offline"
+    tags = _get("/api/tags") or {}
+    names = [m.get("name", "") for m in tags.get("models", [])]
+    hers = [n for n in names if n.startswith("cosmos-phos")] or \
+           [n for n in names if n.startswith(("cosmos-cst", "cosmos-spark"))]
+    if not hers:
+        return OK, DEAD, DEAD, "no model of hers to speak through"
+    model = hers[0]
+    r = _post("/api/chat", {
+        "model": model,
+        "messages": [{"role": "user", "content": "hello"}],
+        "stream": False,
+        "options": {"num_predict": 24},
+    })
+    if r is None:
+        return OK, OK, DEAD, f"{model} accepted no request (timeout or error)"
+    text = ((r.get("message") or {}).get("content") or r.get("response") or "").strip()
+    if not text:
+        return OK, OK, DEAD, f"{model} answered with an empty string"
+    snip = text.replace("\n", " ")[:58]
+    return OK, OK, OK, f"{model} said: \"{snip}{'...' if len(text) > 58 else ''}\""
+
+
+def check_coder():
+    p = ROOT / "serving" / "cosmos_coder.py"
+    if not p.exists():
+        return DEAD, DEAD, DEAD, "serving/cosmos_coder.py is missing"
+    src = p.read_text(encoding="utf-8", errors="ignore")
+    loads = OK
+    try:
+        compile(src, str(p), "exec")
+    except SyntaxError as e:
+        return OK, DEAD, DEAD, f"will not compile: line {e.lineno}"
+    ws = ROOT / "workspace"
+    try:
+        ws.mkdir(exist_ok=True)
+        probe = ws / ".health_probe"
+        probe.write_text("ok", encoding="utf-8")
+        probe.unlink()
+    except Exception as e:
+        return OK, loads, DEAD, f"workspace not writable: {type(e).__name__}"
+    switching = "/model" in src and "/models" in src
+    if not switching:
+        return OK, loads, DEAD, "compiles, but has no /model switching"
+    return OK, loads, OK, "compiles, workspace writable, /model switching present"
+
+
+def check_no_secrets():
+    """A release must not carry credentials. This is the gate that was skipped."""
+    cfg = ROOT / "genesis_engine" / "config.json"
+    if not cfg.exists():
+        return WARN, WARN, WARN, "genesis_engine/config.json absent (fine if intentional)"
+    try:
+        d = json.loads(cfg.read_text(encoding="utf-8"))
+    except Exception as e:
+        return OK, DEAD, DEAD, f"config.json will not parse: {type(e).__name__}"
+    filled = [k for k in ("ibm_token", "azure_connection_string")
+              if str(d.get(k) or "").strip()]
+    if filled:
+        return OK, OK, DEAD, f"CREDENTIAL PRESENT in config.json: {', '.join(filled)} -- do not upload"
+    forbidden = []
+    for pat in (".ledger_key", "oauth2_tokens.json", ".env", "credentials.json",
+                ".coder_history.jsonl", "memory.jsonl", "ledger.jsonl"):
+        forbidden += [p for p in ROOT.rglob(pat) if p.is_file()]
+    if forbidden:
+        rels = ", ".join(str(p.relative_to(ROOT)) for p in forbidden[:4])
+        return OK, OK, DEAD, f"private files staged: {rels}"
+    return OK, OK, OK, "no credentials, no private files staged"
+
+
+def check_docs():
+    need = ["README.md", "START_HERE.md", "FINDINGS.md", "QUANTUM_CREATURE.md", "LICENSE.md"]
+    missing = [n for n in need if not (ROOT / n).exists()]
+    if missing:
+        return DEAD, DEAD, DEAD, f"missing: {', '.join(missing)}"
+    readme = (ROOT / "README.md").read_text(encoding="utf-8", errors="ignore")
+    head = readme[:2000].lower()
+    if "qwen" in head.split("## ")[0]:
+        return OK, OK, DEAD, "README leads with qwen instead of her own work"
+    if "phos" not in head:
+        return OK, OK, DEAD, "README does not lead with PHOS"
+    return OK, OK, OK, f"{len(need)} docs present, README leads with PHOS"
+
+
+CHECKS = [
+    ("python + torch", check_python),
+    ("PHOS weights", lambda: check_weight("PHOS", "phos.pt")),
+    ("CST weights", lambda: check_weight("CST", "spark_cst.pt")),
+    ("quantum-born weights", lambda: check_weight("born", "cosmos_born.pt")),
+    ("her model server", check_server),
+    ("HER VOICE (round trip)", check_voice),
+    ("the coder", check_coder),
+    ("no secrets shipped", check_no_secrets),
+    ("docs + model card", check_docs),
+]
+
+
+def main() -> int:
+    w = 76
+    print("=" * w)
+    print("  KIT HEALTH   PRESENT -> LOADS -> ANSWERS")
+    print("=" * w)
+    print("  A part is alive only if all three hold. Two of three is exactly the")
+    print("  condition that lets a broken kit report that it is fine.\n")
+
+    bad = []
+    for name, fn in CHECKS:
+        try:
+            present, loads, answers, detail = fn()
+        except Exception as e:
+            present = loads = answers = DEAD
+            detail = f"check itself raised {type(e).__name__}: {e}"
+        trio = [present, loads, answers]
+        alive = all(t == OK for t in trio)
+        soft = all(t == WARN for t in trio)
+        if not alive and not soft:
+            bad.append((name, trio, detail))
+        if QUIET and (alive or soft):
+            continue
+        mark = "OK " if alive else ("~  " if soft else "XX ")
+        print(f"  {mark} {name}")
+        print(f"       PRESENT {present:<5} LOADS {loads:<5} ANSWERS {answers:<5}  {detail}")
+
+    print("\n" + "=" * w)
+    print(f"  {len(CHECKS) - len(bad)}/{len(CHECKS)} parts alive on all three")
+    if bad:
+        print("\n  needs attention:")
+        for name, trio, detail in bad:
+            miss = [lbl for lbl, v in zip(("PRESENT", "LOADS", "ANSWERS"), trio) if v != OK]
+            print(f"    - {name}: {', '.join(miss)}")
+            print(f"        {detail}")
+        print("\n  most failures here are fixed by menu option 3 (start her model server).")
+        return 1
+    print("  everything works. Nothing is quietly doing nothing.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())