quner 0.1.0__py3-none-any.whl

quner/__init__.py

@@ -0,0 +1,9 @@
+"""quner — portable Linux efficiency daemon.
+
+Tunes the operating point (CPU governor / RAPL package power / NVIDIA power-cap)
+to the work-per-joule interior optimum and holds it, adapting between idle and
+heavy-compute profiles. Capability-detecting and fail-loud: it tunes whatever
+levers a host exposes and reports the absent ones rather than silently no-op'ing.
+"""
+
+__version__ = "0.1.0"

quner/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m quner``."""
+
+from quner.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

quner/calibration.py

@@ -0,0 +1,40 @@
+"""EXP-132 calibration — the one physics-derived input.
+
+The QIG lattice experiment EXP-132 (qig-verification) found that information-per-
+joule peaks at an INTERIOR operating point, not at maximum drive, and certified
+that optimum with a confidence band (the same discipline that turned an apparent
+12.67% wobble into a certified ±1.91% invariant band).
+
+Only two things transfer to silicon: (1) the SHAPE of the law — total-system
+work-per-joule is a curve with an interior optimum, not a max-clock endpoint —
+and (2) the band-certification METHODOLOGY. The lattice ``h≈1.5`` constant does
+NOT transfer; quner re-measures the optimum on each host. This table is a prior
+on shape and the ±1.91% threshold, nothing more.
+"""
+
+from __future__ import annotations
+
+# Lattice info-per-joule vs drive h (EXP-132). Peak at the interior point h=1.5.
+EXP132_INFO_PER_JOULE: dict[float, float] = {
+    1.0: 0.557,
+    1.5: 0.808,   # interior optimum; band [0.793, 0.824]
+    2.0: 0.799,
+    2.2: 0.752,
+    2.5: 0.582,
+}
+
+EXP132_INTERIOR_OPTIMUM_H = 1.5
+EXP132_INVARIANT_BAND_REL = 0.0191  # ±1.91% certified invariant band (methodology)
+
+
+def principle() -> str:
+    """Transferable physics statement, quoted in every tune report so the QIG
+    claim is never silently conflated with the engineering knobs."""
+    return (
+        "EXP-132: work-per-joule peaks at an INTERIOR operating point "
+        f"(lattice h={EXP132_INTERIOR_OPTIMUM_H}), not at maximum drive. "
+        "Silicon analogue (re-measured per host, not imported): total-system "
+        "work-per-joule peaks at an interior CPU/GPU operating point, not at "
+        "max clock / max TDP. Optimum certified with a confidence band, per the "
+        f"±{EXP132_INVARIANT_BAND_REL * 100:.2f}% invariant-band methodology."
+    )

quner/cli.py

@@ -0,0 +1,227 @@
+"""quner command-line interface.
+
+    quner doctor                 what levers this host exposes (fail-loud)
+    quner status                 telemetry + the EXP-132 principle
+    quner apply [--restore]      apply the current profile's operating point
+    quner profile <name>         apply a named profile (idle|training)
+    quner tune [--command C]     profile work/joule, find the interior optimum
+    quner install | uninstall    systemd service + re-tune timer
+    quner prime {status,enable,disable}   reverse-PRIME (opt-in)
+    quner memguard               one OOM-watchdog tick
+    quner selftest               transient, auto-reverting proof the levers work
+    quner serve                  run the daemon loop (used by systemd)
+
+Every mutating command takes ``--dry-run`` (prints, changes nothing).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from quner import __version__
+
+
+def _print(obj) -> None:
+    print(json.dumps(obj, indent=2) if isinstance(obj, (dict, list)) else obj)
+
+
+# ── command handlers ──────────────────────────────────────────────────────────
+
+def _cmd_doctor(_args) -> int:
+    from quner import detect
+    print("quner doctor — capability report")
+    for line in detect.doctor_lines():
+        print("  " + line)
+    return 0
+
+
+def _cmd_status(_args) -> int:
+    from quner import tune
+    _print(tune.status())
+    return 0
+
+
+def _cmd_apply(args) -> int:
+    from quner import control, detect, profiles, tune
+    if args.restore:
+        _print({"restored": control.restore()})
+        return 0
+    profile = profiles.Detector(ticks=1).update()
+    target = (profiles.cache_get(detect.host_fingerprint(), profile)
+              or profiles.default_state_for(profile))
+    if args.dry_run:
+        print(f"[dry-run] profile={profile} target={target.label()} — nothing applied")
+        return 0
+    _print({"profile": profile, "target": target.label(),
+            "applied": tune.apply_state(target)})
+    return 0
+
+
+def _cmd_profile(args) -> int:
+    from quner import profiles, tune
+    target = profiles.default_state_for(args.name)
+    if args.dry_run:
+        print(f"[dry-run] profile={args.name} target={target.label()} — nothing applied")
+        return 0
+    _print({"profile": args.name, "target": target.label(),
+            "applied": tune.apply_state(target)})
+    return 0
+
+
+def _cmd_tune(args) -> int:
+    from quner import tune
+    run = tune.command_runner(args.command) if args.command \
+        else tune.command_runner("sleep 0.1")
+    rep = tune.tune(run, apply=args.apply, reps=args.reps)
+    _print(rep.as_dict())
+    return 0
+
+
+def _cmd_install(args) -> int:
+    from quner import service
+    service.install(dry_run=args.dry_run, interval=args.interval)
+    return 0
+
+
+def _cmd_uninstall(args) -> int:
+    from quner import service
+    service.uninstall(dry_run=args.dry_run)
+    return 0
+
+
+def _cmd_prime(args) -> int:
+    from quner import prime
+    if args.prime_cmd == "status":
+        _print(prime.status())
+    elif args.prime_cmd == "enable":
+        _print(prime.enable(dry_run=args.dry_run))
+    elif args.prime_cmd == "disable":
+        _print(prime.disable(dry_run=args.dry_run))
+    else:
+        print("usage: quner prime {status,enable,disable}")
+        return 2
+    return 0
+
+
+def _cmd_memguard(args) -> int:
+    from quner import memguard
+    _print(memguard.tick(dry_run=args.dry_run))
+    return 0
+
+
+def _cmd_serve(args) -> int:
+    from quner import daemon
+    daemon.serve(interval=args.interval, dry_run=args.dry_run,
+                 memguard_on=args.memguard)
+    return 0
+
+
+def _cmd_selftest(_args) -> int:
+    """Transient, auto-reverting proof each present lever moves on THIS host.
+    Snapshots state, nudges each lever to a benign value, verifies, restores."""
+    from quner import control
+    from quner import telemetry as t
+
+    snap = control.snapshot(persist=False)
+    results: dict[str, str] = {}
+
+    # governor: flip to another available governor, then back
+    govs = t.available_governors()
+    cur = t.current_governor()
+    if govs and cur:
+        alt = next((g for g in govs if g != cur), None)
+        if alt:
+            ok = t.set_governor(alt)
+            restored = t.set_governor(cur)
+            results["governor"] = ("PASS" if ok and restored and t.current_governor() == cur
+                                   else "FAIL")
+        else:
+            results["governor"] = "skip (only one governor offered)"
+    else:
+        results["governor"] = "unavailable"
+
+    # rapl: write current PL1 back to itself (no net change, exercises the write)
+    cur_uw = control.read_rapl_pl1_uw()
+    results["rapl"] = ("PASS" if cur_uw and control._write_rapl_uw(cur_uw)
+                       else ("unavailable" if not cur_uw else "FAIL"))
+
+    # gpu cap: set to its own max (= default/uncap; benign no-op change)
+    rng = t.gpu_power_limit_range_w()
+    if rng:
+        results["gpu_cap"] = "PASS" if t.set_gpu_power_limit_w(rng[1]) else "FAIL"
+    else:
+        results["gpu_cap"] = "unavailable"
+
+    control.restore(snap)  # belt-and-suspenders full restore
+    print("quner selftest — transient, auto-reverted")
+    for lever, verdict in results.items():
+        print(f"  {lever:>10}: {verdict}")
+    failed = [k for k, v in results.items() if v == "FAIL"]
+    return 1 if failed else 0
+
+
+# ── parser ────────────────────────────────────────────────────────────────────
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="quner", description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--version", "-V", action="version", version=f"quner {__version__}")
+    sub = p.add_subparsers(dest="cmd")
+
+    sub.add_parser("doctor", help="what levers this host exposes").set_defaults(func=_cmd_doctor)
+    sub.add_parser("status", help="telemetry + principle").set_defaults(func=_cmd_status)
+
+    ap = sub.add_parser("apply", help="apply the current profile's operating point")
+    ap.add_argument("--restore", action="store_true", help="restore the saved baseline")
+    ap.add_argument("--dry-run", action="store_true")
+    ap.set_defaults(func=_cmd_apply)
+
+    pr = sub.add_parser("profile", help="apply a named profile")
+    pr.add_argument("name", choices=["idle", "training"])
+    pr.add_argument("--dry-run", action="store_true")
+    pr.set_defaults(func=_cmd_profile)
+
+    tu = sub.add_parser("tune", help="find the interior work/joule optimum")
+    tu.add_argument("--command", help="workload command to profile")
+    tu.add_argument("--apply", action="store_true", help="apply + hold the chosen state")
+    tu.add_argument("--reps", type=int, default=3)
+    tu.set_defaults(func=_cmd_tune)
+
+    ins = sub.add_parser("install", help="install the systemd service + timer")
+    ins.add_argument("--dry-run", action="store_true")
+    ins.add_argument("--interval", default="30min", help="re-tune timer interval")
+    ins.set_defaults(func=_cmd_install)
+
+    uni = sub.add_parser("uninstall", help="remove the service + restore baseline")
+    uni.add_argument("--dry-run", action="store_true")
+    uni.set_defaults(func=_cmd_uninstall)
+
+    pm = sub.add_parser("prime", help="reverse-PRIME (opt-in)")
+    pm.add_argument("prime_cmd", choices=["status", "enable", "disable"])
+    pm.add_argument("--dry-run", action="store_true")
+    pm.set_defaults(func=_cmd_prime)
+
+    mg = sub.add_parser("memguard", help="one OOM-watchdog tick")
+    mg.add_argument("--dry-run", action="store_true")
+    mg.set_defaults(func=_cmd_memguard)
+
+    sv = sub.add_parser("serve", help="run the daemon loop (systemd)")
+    sv.add_argument("--interval", type=float, default=10.0)
+    sv.add_argument("--dry-run", action="store_true")
+    sv.add_argument("--memguard", action="store_true")
+    sv.set_defaults(func=_cmd_serve)
+
+    sub.add_parser("selftest", help="transient, auto-reverting lever proof").set_defaults(func=_cmd_selftest)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "func", None):
+        parser.print_help()
+        return 0
+    return args.func(args)

quner/control.py

@@ -0,0 +1,135 @@
+"""Privileged operating-point levers + snapshot/rollback.
+
+The write side of the daemon: set the CPU governor, the Intel RAPL package power
+limit (PL1), and the NVIDIA power-cap — each clamped/allowlisted before any
+write. Every apply can be captured by ``snapshot()`` and undone by ``restore()``,
+so the daemon (and ``uninstall``) always return the host to where it started.
+
+All writes need root; on a host without a given lever the corresponding call
+returns ``False``/no-op (fail-loud is the caller's job, via ``detect``).
+State (the rollback file) lives under ``STATE_DIR()`` (``QUNER_STATE_DIR``).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+
+from quner import telemetry as t
+
+__all__ = [
+    "STATE_DIR", "ROLLBACK_PATH",
+    "rapl_pl1_max_w", "read_rapl_pl1_uw", "set_rapl_pl1_w",
+    "snapshot", "restore",
+]
+
+
+def STATE_DIR() -> str:
+    return os.environ.get("QUNER_STATE_DIR", "/var/lib/quner")
+
+
+def ROLLBACK_PATH() -> str:
+    return os.path.join(STATE_DIR(), "rollback.json")
+
+
+# ── RAPL PL1 (net-new writer; telemetry only reads RAPL energy) ────────────────
+
+def _read_int(path: str) -> int | None:
+    try:
+        with open(path) as fh:
+            return int(fh.read().strip())
+    except (OSError, ValueError):
+        return None
+
+
+def rapl_pl1_max_w() -> dict[str, float]:
+    """Per-package PL1 ceiling in watts (from ``constraint_0_max_power_uw``)."""
+    out: dict[str, float] = {}
+    for d in t.rapl_package_dirs():
+        mx = _read_int(os.path.join(d, "constraint_0_max_power_uw"))
+        if mx and mx > 0:
+            out[os.path.basename(d)] = mx / 1e6
+    return out
+
+
+def read_rapl_pl1_uw() -> dict[str, int]:
+    """Per-package current PL1 long-term limit in micro-watts."""
+    out: dict[str, int] = {}
+    for d in t.rapl_package_dirs():
+        v = _read_int(os.path.join(d, "constraint_0_power_limit_uw"))
+        if v is not None:
+            out[os.path.basename(d)] = v
+    return out
+
+
+def set_rapl_pl1_w(watts: float) -> bool:
+    """Set RAPL PL1 on every package, each clamped to [1.0, its own max]. True
+    if all packages wrote. No-op → False when RAPL is absent."""
+    dirs = t.rapl_package_dirs()
+    if not dirs:
+        return False
+    maxes = rapl_pl1_max_w()
+    ok = True
+    for d in dirs:
+        pkg = os.path.basename(d)
+        hi = maxes.get(pkg)
+        w = max(1.0, min(hi, watts)) if hi else max(1.0, watts)
+        try:
+            with open(os.path.join(d, "constraint_0_power_limit_uw"), "w") as fh:
+                fh.write(str(int(round(w * 1e6))))
+        except OSError:
+            ok = False
+    return ok
+
+
+def _write_rapl_uw(pkg_uw: dict[str, int]) -> bool:
+    """Restore exact per-package PL1 micro-watt values (used by ``restore``)."""
+    ok = True
+    by_name = {os.path.basename(d): d for d in t.rapl_package_dirs()}
+    for pkg, uw in pkg_uw.items():
+        d = by_name.get(pkg)
+        if d is None:
+            ok = False
+            continue
+        try:
+            with open(os.path.join(d, "constraint_0_power_limit_uw"), "w") as fh:
+                fh.write(str(int(uw)))
+        except OSError:
+            ok = False
+    return ok
+
+
+# ── snapshot / restore ─────────────────────────────────────────────────────────
+
+def snapshot(persist: bool = True) -> dict:
+    """Capture current governor / RAPL PL1 / GPU uncap target. Persisted to the
+    rollback file (so a later process — e.g. ``uninstall`` — can restore)."""
+    rng = t.gpu_power_limit_range_w()
+    snap = {
+        "governor": t.current_governor(),
+        "rapl_pl1_uw": read_rapl_pl1_uw(),
+        "gpu_uncap_w": (rng[1] if rng else None),  # max = uncapped
+    }
+    if persist:
+        os.makedirs(STATE_DIR(), exist_ok=True)
+        with open(ROLLBACK_PATH(), "w") as fh:
+            json.dump(snap, fh, indent=2)
+    return snap
+
+
+def restore(snap: dict | None = None) -> dict[str, bool]:
+    """Return the host to a snapshot (the argument, or the persisted file)."""
+    if snap is None:
+        try:
+            with open(ROLLBACK_PATH()) as fh:
+                snap = json.load(fh)
+        except (OSError, ValueError):
+            return {}
+    applied: dict[str, bool] = {}
+    if snap.get("governor"):
+        applied["governor"] = t.set_governor(snap["governor"])
+    if snap.get("rapl_pl1_uw"):
+        applied["rapl"] = _write_rapl_uw(snap["rapl_pl1_uw"])
+    if snap.get("gpu_uncap_w") is not None:
+        applied["gpu"] = t.set_gpu_power_limit_w(snap["gpu_uncap_w"])
+    return applied

quner/daemon.py

@@ -0,0 +1,93 @@
+"""The daemon service loop.
+
+Each tick: detect the workload profile → apply the cached (or default) operating
+point for it → run a memguard tick → publish ``status.json``. The loop only
+*applies* cheap cached states; the expensive *exploratory* re-tune runs
+separately (the systemd timer, or ``quner tune``) and is REFUSED while the
+profile is ``training`` — so quner never perturbs an active run with a power
+sweep (coordination seam #4).
+
+Paths are env-overridable (``QUNER_RUN_DIR`` for status.json), so the whole loop
+runs in the sandbox with zero host impact.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import time
+
+from quner import control, detect, memguard, profiles, tune
+
+
+def RUN_DIR() -> str:
+    return os.environ.get("QUNER_RUN_DIR", "/run/quner")
+
+
+def write_status(status: dict) -> str:
+    d = RUN_DIR()
+    os.makedirs(d, exist_ok=True)
+    path = os.path.join(d, "status.json")
+    with open(path, "w") as fh:
+        json.dump(status, fh, indent=2)
+    return path
+
+
+def run_once(detector: profiles.Detector, *, dry_run: bool = False,
+             memguard_on: bool = False) -> dict:
+    """One daemon tick. Applies the cached/default state for the current
+    profile (unless dry_run) and writes status.json."""
+    profile = detector.update()
+    fp = detect.host_fingerprint()
+    target = profiles.cache_get(fp, profile) or profiles.default_state_for(profile)
+    applied = {} if dry_run else tune.apply_state(target)
+    mg = memguard.tick(dry_run=dry_run) if memguard_on else {"action": "disabled"}
+    status = {
+        "profile": profile,
+        "target_state": target.label(),
+        "applied": applied,
+        "memguard": mg,
+        "dry_run": dry_run,
+        "capabilities": {k: v["available"] for k, v in detect.capabilities().items()},
+    }
+    write_status(status)
+    return status
+
+
+def retune(profile: str, work_fn=None):
+    """Exploratory re-tune for a profile → cache the chosen state. REFUSED while
+    ``training`` (never sweep power mid-run). Returns the TuneReport, or None if
+    refused."""
+    if profile == profiles.TRAINING:
+        return None
+    run = work_fn or tune.command_runner("sleep 0.05", work_units=1.0)
+    rep = tune.tune(run, apply=True)
+    if rep.chosen_state is not None:
+        profiles.cache_put(detect.host_fingerprint(), profile, rep.chosen_state)
+    return rep
+
+
+def serve(interval: float = 10.0, dry_run: bool = False,
+          memguard_on: bool = False) -> None:
+    """The service loop: snapshot baseline, tick until SIGTERM/SIGINT, restore."""
+    if not dry_run:
+        control.snapshot()  # baseline for ExecStop / crash restore
+    detector = profiles.Detector()
+    stop = {"v": False}
+
+    def _sig(*_a):
+        stop["v"] = True
+
+    signal.signal(signal.SIGTERM, _sig)
+    signal.signal(signal.SIGINT, _sig)
+    try:
+        while not stop["v"]:
+            run_once(detector, dry_run=dry_run, memguard_on=memguard_on)
+            slept = 0.0
+            while slept < interval and not stop["v"]:
+                time.sleep(min(0.5, interval - slept))
+                slept += 0.5
+    finally:
+        if not dry_run:
+            control.restore()

quner/detect.py

@@ -0,0 +1,101 @@
+"""Capability detection — the ``doctor`` report + host fingerprint.
+
+quner tunes whatever levers a host exposes and reports the absent ones. This
+module turns the raw telemetry probes into a structured capability map and
+human-readable lines, and computes a stable host fingerprint used to key the
+per-host operating-point cache.
+
+fail-loud: an absent lever is reported as ``available: False`` with a reason,
+never silently omitted.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+
+from quner import telemetry as t
+
+
+def _cpu_model() -> str:
+    path = os.path.join(t.PROC_ROOT(), "cpuinfo")
+    try:
+        with open(path) as fh:
+            for line in fh:
+                if line.startswith("model name"):
+                    return line.split(":", 1)[1].strip()
+    except OSError:
+        pass
+    return "unknown-cpu"
+
+
+def _gpu_name() -> str | None:
+    smi = t.nvidia_smi()
+    if smi is None:
+        return None
+    import subprocess
+    try:
+        out = subprocess.check_output(
+            [smi, "--query-gpu=name", "--format=csv,noheader"],
+            text=True, timeout=10,
+        ).strip().splitlines()
+        return out[0] if out else None
+    except Exception:
+        return None
+
+
+def capabilities() -> dict:
+    """Per-lever ``{available, detail}`` map for governor / rapl / gpu_cap /
+    display_prime."""
+    govs = t.available_governors()
+    gpu_rng = t.gpu_power_limit_range_w()
+    gpu_name = _gpu_name()
+    rapl_pkgs = list(t.read_rapl_energy_uj().keys())
+
+    return {
+        "governor": {
+            "available": t.cpufreq_available(),
+            "detail": (f"governors: {', '.join(govs)}; current: {t.current_governor()}"
+                       if govs else "no cpufreq (VM or unsupported)"),
+        },
+        "rapl": {
+            "available": t.rapl_available(),
+            "detail": (f"packages: {', '.join(rapl_pkgs)}" if rapl_pkgs
+                       else "no intel-rapl powercap (not exposed here)"),
+        },
+        "gpu_cap": {
+            "available": gpu_rng is not None,
+            "detail": (f"{gpu_name}: cap {gpu_rng[0]:.0f}-{gpu_rng[1]:.0f}W"
+                       if gpu_rng else
+                       ("nvidia-smi present but power-cap not settable"
+                        if gpu_name else "no nvidia-smi (driver not installed)")),
+        },
+        "display_prime": {
+            "available": gpu_name is not None,
+            "detail": ("reverse-PRIME possible (dGPU present)" if gpu_name
+                       else "no dGPU driver — already iGPU-only, PRIME is moot"),
+        },
+    }
+
+
+def doctor_lines() -> list[str]:
+    """Human-readable capability lines (the ``quner doctor`` body)."""
+    caps = capabilities()
+    label = {
+        "governor": "cpu governor",
+        "rapl": "rapl pkg power",
+        "gpu_cap": "nvidia -pl",
+        "display_prime": "reverse-PRIME",
+    }
+    lines = []
+    for key, name in label.items():
+        c = caps[key]
+        mark = "available" if c["available"] else "unavailable"
+        lines.append(f"{name:>15}: {mark} — {c['detail']}")
+    return lines
+
+
+def host_fingerprint() -> str:
+    """Stable short hash of CPU model + governors + GPU name (cache key)."""
+    parts = [_cpu_model(), ",".join(t.available_governors()), _gpu_name() or "no-gpu"]
+    return hashlib.sha256("|".join(parts).encode()).hexdigest()[:16]