giul 0.1.0__py3-none-any.whl

giul/__init__.py

@@ -0,0 +1,41 @@
+"""giul — one ruler for what an answer cost in joules.
+
+*giúl*, Irish for joule. Aigne, Tuiscint and Gléas each need to say what a
+request cost in energy; two rulers make a comparison an argument instead of
+evidence, so there is one, and all three pin it.
+
+    from giul import Meter, Node
+
+    node = Node(name="iris", gpu_index=0, idle_w=38.0, is_local=True)
+    async with Meter.for_node(node, joules_per_1k_hint=4100.0) as m:
+        await retrieve(); m.mark("retrieve")
+        await generate(); m.mark("generate")
+    e = m.result(tokens=412)
+
+Three rules the library will not bend:
+
+1. A request is charged above idle — for the power it caused, not the power
+   the box burns existing. ``idle_w`` comes from the caller; giul never
+   guesses it.
+2. A window that measured <= 0 J above idle failed to measure a request; it
+   did not measure a free one. It degrades to ``estimated`` or ``unknown``,
+   never a ``sampled`` zero.
+3. Estimates are labelled as estimates. A sampler that cannot be reached
+   costs a measurement, never the request.
+"""
+
+from .backends import NvmlCounter, RemoteAgent, SmiSampler
+from .meter import Energy, EnergyMeter, Meter, Node
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Energy",
+    "EnergyMeter",
+    "Meter",
+    "Node",
+    "NvmlCounter",
+    "RemoteAgent",
+    "SmiSampler",
+    "__version__",
+]

giul/agent.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Expose a node's GPU power draw over HTTP, so giul can meter remote tiers.
+
+`nvidia-smi` only sees the card in the machine it runs on, which meant every
+node except the gateway's own reported "energy not measured here". That makes
+the fleet's headline metric a single-node metric. This closes it.
+
+Deliberately stdlib-only and dependency-free: it has to run on any fleet node
+without provisioning a venv, and it must not be able to break a serving node.
+It reads power and nothing else — no control surface, no writes.
+
+    giul-agent --port 9402
+    curl localhost:9402/power?gpu=1   -> {"watts": 231.4, "gpu": 1, ...}
+
+Bind to the Féith mesh address, not 0.0.0.0, unless the node is otherwise
+firewalled.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlparse
+
+SMI = "nvidia-smi"
+QUERY_TIMEOUT_S = 5.0
+
+
+def read_gpu(index: int) -> dict:
+    """Instantaneous board draw for one GPU, plus enough to identify it.
+
+    The name is included so a caller can assert it is metering the card it
+    thinks it is — a wrong `gpu_index` otherwise silently reports an idle
+    neighbour, which reads as "this model is astonishingly efficient".
+    """
+    out = subprocess.run(
+        [SMI, f"--id={index}",
+         "--query-gpu=name,power.draw,memory.used,utilization.gpu",
+         "--format=csv,noheader,nounits"],
+        capture_output=True, text=True, timeout=QUERY_TIMEOUT_S, check=True,
+    ).stdout.strip()
+    name, watts, mem, util = (p.strip() for p in out.split(",", 3))
+    return {
+        "gpu": index,
+        "name": name,
+        "watts": float(watts),
+        "memory_used_mib": int(float(mem)),
+        "utilization_pct": int(float(util)),
+    }
+
+
+class Handler(BaseHTTPRequestHandler):
+    default_gpu = 0
+
+    def _send(self, code: int, payload: dict) -> None:
+        body = json.dumps(payload).encode()
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def do_GET(self) -> None:  # noqa: N802 (stdlib naming)
+        url = urlparse(self.path)
+        if url.path not in ("/power", "/healthz"):
+            return self._send(404, {"error": "try /power or /healthz"})
+
+        params = parse_qs(url.query)
+        try:
+            index = int(params.get("gpu", [self.default_gpu])[0])
+        except ValueError:
+            return self._send(400, {"error": "gpu must be an integer"})
+
+        try:
+            self._send(200, read_gpu(index))
+        except subprocess.CalledProcessError as exc:
+            self._send(404, {"error": f"no gpu {index}", "detail": exc.stderr.strip()[:200]})
+        except (subprocess.SubprocessError, FileNotFoundError, ValueError) as exc:
+            # Never 500 into the gateway's request path: an unreadable sampler
+            # must degrade to "unmeasured", not to a failed completion.
+            self._send(503, {"error": f"{type(exc).__name__}: {exc}"})
+
+    def log_message(self, *args) -> None:
+        """Silent: this is polled several times a second per request."""
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--host", default="0.0.0.0")
+    ap.add_argument("--port", type=int, default=9402)
+    ap.add_argument("--gpu", type=int, default=0, help="default GPU when ?gpu= is omitted")
+    args = ap.parse_args()
+
+    Handler.default_gpu = args.gpu
+    print(f"power-agent on {args.host}:{args.port}, default gpu {args.gpu}", flush=True)
+    ThreadingHTTPServer((args.host, args.port), Handler).serve_forever()
+
+
+if __name__ == "__main__":
+    main()

giul/backends.py

@@ -0,0 +1,232 @@
+"""Three ways to ask a GPU what it drew, and one that cannot ask.
+
+Two shapes of answer, not one:
+
+- A **counter** backend (``nvml_counter``) reads a cumulative millijoule
+  register the driver maintains. Two reads and a subtraction give a true
+  delta over the window, with no sampling resolution to fall through. This
+  is why sub-second requests can be measured at all.
+- A **sampler** backend (``smi_sampler``, ``remote_agent``) reads
+  instantaneous watts and the meter integrates them. Fine for multi-second
+  windows, blind below its poll interval.
+
+Every read returns ``None`` rather than raising. A sampler that cannot be
+reached must degrade the request to unmeasured, never fail it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import shutil
+import subprocess
+
+SMI = shutil.which("nvidia-smi")
+
+COUNTER = "counter"
+SAMPLER = "sampler"
+
+
+def read_power_w(gpu_index: int = 0) -> float | None:
+    """Instantaneous board draw in watts, or None if nvidia-smi can't say."""
+    if not SMI:
+        return None
+    try:
+        out = subprocess.run(
+            [SMI, f"--id={gpu_index}", "--query-gpu=power.draw",
+             "--format=csv,noheader,nounits"],
+            capture_output=True, text=True, timeout=5, check=True,
+        ).stdout.strip()
+        return float(out.splitlines()[0])
+    except (subprocess.SubprocessError, ValueError, IndexError, OSError):
+        return None
+
+
+class Backend:
+    """Something that can be asked about a card, without saying how."""
+
+    name = "none"
+    kind = "none"
+
+    def read_watts(self) -> float | None:
+        return None
+
+    async def aread_watts(self) -> float | None:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self.read_watts)
+
+    def read_joules(self) -> float | None:
+        """Cumulative joules since driver load. Counter backends only."""
+        return None
+
+    async def aread_joules(self) -> float | None:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, self.read_joules)
+
+    def close(self) -> None:
+        pass
+
+    async def aclose(self) -> None:
+        self.close()
+
+
+class NvmlCounter(Backend):
+    """``nvmlDeviceGetTotalEnergyConsumption`` — a real energy register.
+
+    Volta and later. Cumulative millijoules since the driver loaded, so the
+    window's joules are one subtraction and carry no sampling error. The
+    caller is responsible for synchronising the GPU before the closing read
+    (see ``Meter``); an unsynchronised read charges the next window for work
+    this one queued.
+    """
+
+    name = "nvml_counter"
+    kind = COUNTER
+
+    def __init__(self, gpu_index: int = 0) -> None:
+        import pynvml  # noqa: PLC0415 — optional, probed at construction
+
+        self._nvml = pynvml
+        self.gpu_index = gpu_index
+        self._handle = pynvml.nvmlDeviceGetHandleByIndex(gpu_index)
+
+    def read_joules(self) -> float | None:
+        try:
+            mj = self._nvml.nvmlDeviceGetTotalEnergyConsumption(self._handle)
+        except Exception:
+            return None
+        return mj / 1000.0
+
+    async def aread_joules(self) -> float | None:
+        # Two register reads; no reason to leave the event loop for it.
+        return self.read_joules()
+
+    def read_watts(self) -> float | None:
+        try:
+            return self._nvml.nvmlDeviceGetPowerUsage(self._handle) / 1000.0
+        except Exception:
+            return None
+
+    async def aread_watts(self) -> float | None:
+        return self.read_watts()
+
+
+class SmiSampler(Backend):
+    """nvidia-smi on this host. Blocking, so async reads go off the loop."""
+
+    name = "smi_sampler"
+    kind = SAMPLER
+
+    def __init__(self, gpu_index: int = 0) -> None:
+        self.gpu_index = gpu_index
+
+    def read_watts(self) -> float | None:
+        return read_power_w(self.gpu_index)
+
+
+class RemoteAgent(Backend):
+    """A fleet node running ``giul-agent``.
+
+    Still a measurement of the real card — only the process running
+    nvidia-smi differs — so it is recorded as ``sampled``, with ``source``
+    distinguishing it from the local path.
+    """
+
+    name = "remote_agent"
+    kind = SAMPLER
+
+    def __init__(self, endpoint: str, gpu_index: int = 0, timeout_s: float = 2.0) -> None:
+        import httpx  # noqa: PLC0415 — optional, only under [remote]
+
+        self._httpx = httpx
+        self.url = endpoint.rstrip("/") + "/power"
+        self.gpu_index = gpu_index
+        self.timeout_s = timeout_s
+        self._aclient: object | None = None
+        self._client: object | None = None
+
+    def read_watts(self) -> float | None:
+        if self._client is None:
+            self._client = self._httpx.Client(timeout=self.timeout_s)
+        try:
+            resp = self._client.get(self.url, params={"gpu": self.gpu_index})
+            if resp.status_code != 200:
+                return None
+            return float(resp.json()["watts"])
+        except (self._httpx.HTTPError, KeyError, ValueError, TypeError):
+            return None
+
+    async def aread_watts(self) -> float | None:
+        if self._aclient is None:
+            self._aclient = self._httpx.AsyncClient(timeout=self.timeout_s)
+        try:
+            resp = await self._aclient.get(self.url, params={"gpu": self.gpu_index})
+            if resp.status_code != 200:
+                return None
+            return float(resp.json()["watts"])
+        except (self._httpx.HTTPError, KeyError, ValueError, TypeError):
+            return None
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+
+    async def aclose(self) -> None:
+        self.close()
+        if self._aclient is not None:
+            await self._aclient.aclose()
+            self._aclient = None
+
+
+# --- backend availability, probed once per card -----------------------------
+#
+# Whether a card supports the energy counter is a property of the silicon and
+# the driver, not of the request, so it is asked once and remembered. A card
+# that does not support it (pre-Volta, or a driver that says NotSupported)
+# falls through to the sampler silently — never into a request.
+
+_nvml_started: bool | None = None
+_counter_support: dict[int, NvmlCounter | None] = {}
+
+
+def _nvml_init() -> bool:
+    """Initialise NVML once. False if pynvml is absent or NVML won't start."""
+    global _nvml_started
+    if _nvml_started is None:
+        try:
+            import pynvml
+
+            pynvml.nvmlInit()
+            _nvml_started = True
+        except Exception:
+            _nvml_started = False
+    return _nvml_started
+
+
+def counter_for(gpu_index: int = 0) -> NvmlCounter | None:
+    """An ``NvmlCounter`` for this card, or None if it has no energy register.
+
+    Support is confirmed by actually taking a reading: a handle that exists
+    but whose counter raises ``NVMLError_NotSupported`` is not support.
+    """
+    if gpu_index in _counter_support:
+        return _counter_support[gpu_index]
+
+    backend: NvmlCounter | None = None
+    if _nvml_init():
+        try:
+            candidate = NvmlCounter(gpu_index)
+            if candidate.read_joules() is not None:
+                backend = candidate
+        except Exception:
+            backend = None
+
+    _counter_support[gpu_index] = backend
+    return backend
+
+
+def reset_probe_cache() -> None:
+    """Forget what was probed. For tests, and for a driver reload."""
+    global _nvml_started
+    _nvml_started = None
+    _counter_support.clear()

giul/meter.py

@@ -0,0 +1,401 @@
+"""Windows, marks, backend selection — joules behind every request.
+
+Every number carries how it was obtained. ``method`` says whether it was
+measured, ``source`` says by whom, ``backend`` says with what:
+
+- ``sampled`` — real joules over the request window, minus the node's idle
+  draw, so a request is charged for the power it *caused* and not for the
+  power the box burns existing. Either a counter delta (``nvml_counter``) or
+  an integral of samples (``smi_sampler``, ``remote_agent``).
+- ``estimated`` — nothing could measure it. Tokens x the tier's
+  joules-per-1k hint. Honest, coarse, and flagged so it can never be
+  mistaken for a measurement.
+- ``unknown`` — not measured and not estimable.
+
+Never silently substitute one for the other: an estimate that reads as a
+measurement is exactly how an efficiency claim stops being evidence.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+
+from .backends import SMI, Backend, RemoteAgent, SmiSampler, counter_for
+
+
+@dataclass(frozen=True)
+class Energy:
+    """What a request cost, and how confidently we know it."""
+
+    joules: float
+    method: str                      # "sampled" | "estimated" | "unknown"
+    seconds: float
+    samples: int = 0
+    mean_watts: float = 0.0
+    idle_watts: float = 0.0
+    source: str = "none"             # "local" | "remote" | "none"
+    backend: str = "none"            # "nvml_counter" | "smi_sampler" |
+                                     # "remote_agent" | "none"
+    stages: Mapping[str, "Energy"] = field(default_factory=dict)
+
+    def per_token(self, tokens: int) -> float | None:
+        return self.joules / tokens if tokens > 0 else None
+
+    def as_dict(self, tokens: int = 0) -> dict:
+        d = {
+            "joules": round(self.joules, 3),
+            "method": self.method,
+            "seconds": round(self.seconds, 4),
+            "samples": self.samples,
+            "mean_watts": round(self.mean_watts, 2),
+            "idle_watts": round(self.idle_watts, 2),
+            "source": self.source,
+            "backend": self.backend,
+        }
+        if (jpt := self.per_token(tokens)) is not None:
+            d["joules_per_token"] = round(jpt, 5)
+            d["tokens_per_joule"] = round(1.0 / jpt, 3) if jpt else None
+        # Only when marks were actually made, so an unmarked window serialises
+        # exactly as it did before stages existed.
+        if self.stages:
+            d["stages"] = {k: v.as_dict() for k, v in self.stages.items()}
+        return d
+
+
+@dataclass(frozen=True)
+class Node:
+    """The card a window is metering, and what it costs at rest.
+
+    ``idle_w`` is supplied by the caller, per node. The library never guesses
+    it: a wrong idle floor silently rewrites every joule figure that node
+    ever reports.
+    """
+
+    name: str = ""
+    gpu_index: int = 0
+    idle_w: float = 0.0
+    is_local: bool = False
+    power_endpoint: str | None = None
+
+
+def _grade(
+    joules: float | None,
+    *,
+    seconds: float,
+    samples: int,
+    mean_watts: float,
+    idle_w: float,
+    source: str,
+    backend: str,
+    tokens: int = 0,
+    hint: float = 0.0,
+    stages: Mapping[str, Energy] | None = None,
+) -> Energy:
+    """Turn a candidate measurement into an ``Energy``, honestly labelled.
+
+    A window that measures <= 0 J above idle did not measure a free request,
+    it failed to measure one. Sub-second windows are below a sampler's
+    resolution: the reading lands before the card ramps, comes back under the
+    idle floor, and charging above idle yields exactly zero. Reporting that
+    as ``sampled`` would put a fabricated zero into the very series the
+    efficiency claim rests on, so it degrades to an estimate instead.
+    """
+    common = dict(seconds=seconds, samples=samples, mean_watts=mean_watts,
+                  idle_watts=idle_w, source=source, backend=backend,
+                  stages=dict(stages or {}))
+
+    if joules is not None and joules > 0:
+        return Energy(joules=joules, method="sampled", **common)
+
+    if tokens > 0 and hint > 0:
+        return Energy(joules=hint * tokens / 1000.0, method="estimated", **common)
+
+    return Energy(joules=0.0, method="unknown", **common)
+
+
+class Meter:
+    """Integrates GPU energy across the life of one request.
+
+    Constructed via :meth:`for_node` so the measured/estimated decision is
+    made in exactly one place. Usable as an async or a sync context manager;
+    ``result()`` is called after the window closes, either way::
+
+        async with Meter.for_node(node) as m:
+            await retrieve(); m.mark("retrieve")
+            await generate(); m.mark("generate")
+        e = m.result(tokens=412)
+
+    **The caller synchronises the GPU before the closing read.** On the
+    counter backend the register only counts work the card has finished, so
+    an in-flight kernel is charged to the *next* window. Pass
+    ``sync=torch.cuda.synchronize`` when the work is local; an HTTP upstream
+    needs nothing, because the completion returning is the sync point.
+    """
+
+    def __init__(
+        self,
+        backend: Backend | None,
+        idle_w: float = 0.0,
+        interval_s: float = 0.25,
+        joules_per_1k_hint: float = 0.0,
+        source: str = "none",
+        sync: Callable[[], None] | None = None,
+    ) -> None:
+        self.backend = backend
+        self.idle_w = idle_w
+        self.interval_s = interval_s
+        self.joules_per_1k_hint = joules_per_1k_hint
+        self.source = source
+        self._sync = sync
+
+        self._watts: list[float] = []            # every watt reading seen
+        self._samples: list[tuple[float, float]] = []   # (t, w), for stages
+        self._marks: list[tuple[str, float, float | None]] = []
+        self._task: asyncio.Task | None = None
+        self._thread: threading.Thread | None = None
+        self._stop = threading.Event()
+        self._t0 = 0.0
+        self._elapsed = 0.0
+        self._j0: float | None = None
+        self._j1: float | None = None
+
+    # --- construction -------------------------------------------------------
+
+    @classmethod
+    def for_node(
+        cls,
+        node,
+        tier=None,
+        interval_s: float = 0.25,
+        *,
+        joules_per_1k_hint: float | None = None,
+        sync: Callable[[], None] | None = None,
+        timeout_s: float = 2.0,
+    ) -> "Meter":
+        """Pick a backend: energy counter, this host's nvidia-smi, a remote
+        agent, or neither.
+
+        Selection is runtime and needs no per-node configuration. Counter
+        support is probed once per card and cached; a card without it falls
+        through to the sampler silently.
+        """
+        hint = joules_per_1k_hint
+        if hint is None:
+            hint = getattr(tier, "joules_per_1k_hint", 0.0) or 0.0
+
+        if node is None:
+            return cls(None, joules_per_1k_hint=hint, interval_s=interval_s, sync=sync)
+
+        common = dict(idle_w=node.idle_w, interval_s=interval_s,
+                      joules_per_1k_hint=hint, sync=sync)
+        gpu_index = getattr(node, "gpu_index", 0)
+
+        if node.is_local:
+            if (counter := counter_for(gpu_index)) is not None:
+                return cls(counter, source="local", **common)
+            if SMI is not None:
+                return cls(SmiSampler(gpu_index), source="local", **common)
+
+        if getattr(node, "power_endpoint", None):
+            try:
+                agent = RemoteAgent(node.power_endpoint, gpu_index, timeout_s)
+            except ImportError:      # httpx absent: no [remote] extra
+                return cls(None, **common)
+            return cls(agent, source="remote", **common)
+
+        return cls(None, **common)
+
+    def sync(self) -> "Meter":
+        """Read as a sync context manager. Same meter, same ``result()``."""
+        return self
+
+    @property
+    def sampling(self) -> bool:
+        return self.backend is not None
+
+    @property
+    def backend_name(self) -> str:
+        return self.backend.name if self.backend is not None else "none"
+
+    # --- marks --------------------------------------------------------------
+
+    def mark(self, name: str) -> None:
+        """Close the current stage at now, and open the next.
+
+        The first stage runs from window open to the first mark. Whatever
+        follows the last mark is part of the total but is not a named stage.
+        """
+        now = time.perf_counter()
+        reading = None
+        if self.backend is not None and self.backend.kind == "counter":
+            reading = self.backend.read_joules()
+        self._marks.append((name, now, reading))
+
+    # --- the window ---------------------------------------------------------
+
+    def _open(self) -> None:
+        self._t0 = time.perf_counter()
+        if self.backend is not None and self.backend.kind == "counter":
+            self._j0 = self.backend.read_joules()
+
+    def _close_clock(self) -> None:
+        """Synchronise, then stop the clock, then take the closing reading.
+
+        In that order: the sync wait is time the request spent, and a counter
+        read before the card has drained charges this window's tail to the
+        next one.
+        """
+        if self._sync is not None:
+            try:
+                self._sync()
+            except Exception:      # a failed sync must not break the request
+                pass
+        self._elapsed = time.perf_counter() - self._t0
+        if self.backend is not None and self.backend.kind == "counter":
+            self._j1 = self.backend.read_joules()
+
+    def _record(self, w: float | None, t: float | None = None) -> None:
+        if w is None:
+            return
+        self._watts.append(w)
+        self._samples.append((t if t is not None else time.perf_counter(), w))
+
+    async def _poll(self) -> None:
+        assert self.backend is not None
+        while True:
+            self._record(await self.backend.aread_watts())
+            await asyncio.sleep(self.interval_s)
+
+    def _poll_sync(self) -> None:
+        assert self.backend is not None
+        while not self._stop.is_set():
+            self._record(self.backend.read_watts())
+            self._stop.wait(self.interval_s)
+
+    @property
+    def _polls(self) -> bool:
+        return self.backend is not None and self.backend.kind == "sampler"
+
+    async def __aenter__(self) -> "Meter":
+        self._open()
+        if self._polls:
+            self._task = asyncio.create_task(self._poll())
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        self._close_clock()
+        # One last reading before tearing down. A sub-second request would
+        # otherwise be characterised entirely by the sample taken at t=0,
+        # which is before the GPU has ramped.
+        if self._polls:
+            try:
+                self._record(await self.backend.aread_watts())
+            except Exception:   # a failed final read must not break the request
+                pass
+        if self._task is not None:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+            self._task = None
+        if self.backend is not None:
+            await self.backend.aclose()
+
+    def __enter__(self) -> "Meter":
+        self._open()
+        if self._polls:
+            self._stop.clear()
+            self._thread = threading.Thread(target=self._poll_sync, daemon=True)
+            self._thread.start()
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self._close_clock()
+        if self._polls:
+            try:
+                self._record(self.backend.read_watts())
+            except Exception:
+                pass
+        if self._thread is not None:
+            self._stop.set()
+            self._thread.join(timeout=self.interval_s + 5.0)
+            self._thread = None
+        if self.backend is not None:
+            self.backend.close()
+
+    # --- the answer ---------------------------------------------------------
+
+    def result(self, tokens: int = 0) -> Energy:
+        """Joules for the window just closed, charged above idle.
+
+        The total is computed over the whole window, never by summing stages,
+        so a stage the sampler was too slow to see cannot corrupt it.
+        """
+        seconds = self._elapsed or (time.perf_counter() - self._t0)
+        joules, mean, samples = self._window(seconds)
+
+        return _grade(
+            joules, seconds=seconds, samples=samples, mean_watts=mean,
+            idle_w=self.idle_w, source=self.source, backend=self.backend_name,
+            tokens=tokens, hint=self.joules_per_1k_hint,
+            stages=self._stages(),
+        )
+
+    def _window(self, seconds: float) -> tuple[float | None, float, int]:
+        """Joules above idle for the whole window, plus what was observed."""
+        if self._j0 is not None and self._j1 is not None:
+            measured = self._j1 - self._j0
+            mean = measured / seconds if seconds > 0 else 0.0
+            # Two reads and a subtraction: a delta, not an integral.
+            return measured - self.idle_w * seconds, mean, 2 + len(self._marks)
+
+        if not self._watts:
+            return None, 0.0, 0
+
+        mean = sum(self._watts) / len(self._watts)
+        above_idle = max(mean - self.idle_w, 0.0)
+        return above_idle * seconds, mean, len(self._watts)
+
+    def _stage_spans(self) -> list[tuple[str, float, float, float | None, float | None]]:
+        """(name, t_start, t_end, counter_at_start, counter_at_end) per stage."""
+        spans = []
+        t_prev, j_prev = self._t0, self._j0
+        for name, t, j in self._marks:
+            spans.append((name, t_prev, t, j_prev, j))
+            t_prev, j_prev = t, j
+        return spans
+
+    def _stages(self) -> dict[str, Energy]:
+        """One ``Energy`` per mark. Empty when no marks were made."""
+        stages: dict[str, Energy] = {}
+        for name, t0, t1, j0, j1 in self._stage_spans():
+            dt = max(t1 - t0, 0.0)
+
+            if j0 is not None and j1 is not None:
+                joules = (j1 - j0) - self.idle_w * dt
+                mean = (j1 - j0) / dt if dt > 0 else 0.0
+                samples = 2
+            else:
+                # Samples that landed inside this stage. A stage shorter than
+                # the poll interval catches none, and reports `unknown` — the
+                # total is unaffected, being computed over the whole window.
+                inside = [w for t, w in self._samples if t0 <= t < t1]
+                samples = len(inside)
+                mean = sum(inside) / samples if samples else 0.0
+                joules = max(mean - self.idle_w, 0.0) * dt if samples else None
+
+            stages[name] = _grade(
+                joules, seconds=dt, samples=samples, mean_watts=mean,
+                idle_w=self.idle_w, source=self.source,
+                backend=self.backend_name,
+            )
+        return stages
+
+
+#: Aigne imported the meter under this name; keep it working across the swap.
+EnergyMeter = Meter

giul/probe.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+"""`giul-probe` — what this host's cards can actually be metered with.
+
+Backend selection is runtime, so nothing needs configuring. But the
+acceptance tests need to know *which* backend they are exercising on which
+card, and "the counter is unsupported on that one" is a fact about the
+silicon worth writing down rather than rediscovering. Run this on each fleet
+node and paste the output into `notes/DECISIONS.md`.
+
+For every GPU it reports the name and driver, whether the power gauge and
+the energy counter answer, and — the point of the exercise — a counter delta
+over a fixed window against the mean of power samples across the same
+window. Those two numbers being close is what says the counter and the
+sampler are the same ruler. On an idle card both are small and the ratio is
+noise; run something on the card if you want the comparison to mean much.
+
+    giul-probe --seconds 2.0
+"""
+
+from __future__ import annotations
+
+import argparse
+import platform
+import shutil
+import subprocess
+import sys
+import time
+
+
+def _nvml():
+    try:
+        import pynvml
+    except ImportError:
+        return None
+    try:
+        pynvml.nvmlInit()
+    except Exception as exc:
+        print(f"pynvml present but NVML would not start: {exc}")
+        return None
+    return pynvml
+
+
+def probe_gpu(nvml, index: int, seconds: float, interval: float) -> None:
+    handle = nvml.nvmlDeviceGetHandleByIndex(index)
+    name = nvml.nvmlDeviceGetName(handle)
+    if isinstance(name, bytes):
+        name = name.decode()
+    print(f"\ngpu {index}: {name}")
+
+    try:
+        watts = nvml.nvmlDeviceGetPowerUsage(handle) / 1000.0
+        print(f"  nvmlDeviceGetPowerUsage:             ok, {watts:.1f} W")
+        gauge = True
+    except Exception as exc:
+        print(f"  nvmlDeviceGetPowerUsage:             {type(exc).__name__}: {exc}")
+        gauge = False
+
+    try:
+        nvml.nvmlDeviceGetTotalEnergyConsumption(handle)
+        print("  nvmlDeviceGetTotalEnergyConsumption: ok  -> backend nvml_counter")
+        counter = True
+    except Exception as exc:
+        print(f"  nvmlDeviceGetTotalEnergyConsumption: {type(exc).__name__}: {exc}")
+        print("  -> no energy counter on this card; selection falls through to smi_sampler")
+        counter = False
+
+    if not (gauge and counter):
+        return
+
+    # The comparison: one delta from the register, one integral from the
+    # gauge, over exactly the same window.
+    samples: list[float] = []
+    j0 = nvml.nvmlDeviceGetTotalEnergyConsumption(handle) / 1000.0
+    t0 = time.perf_counter()
+    while (elapsed := time.perf_counter() - t0) < seconds:
+        samples.append(nvml.nvmlDeviceGetPowerUsage(handle) / 1000.0)
+        time.sleep(interval)
+    elapsed = time.perf_counter() - t0
+    j1 = nvml.nvmlDeviceGetTotalEnergyConsumption(handle) / 1000.0
+
+    counter_j = j1 - j0
+    mean_w = sum(samples) / len(samples) if samples else 0.0
+    sampled_j = mean_w * elapsed
+    ratio = counter_j / sampled_j if sampled_j else float("nan")
+
+    print(f"  window: {elapsed:.3f} s, {len(samples)} power samples at {interval}s")
+    print(f"  counter delta:  {counter_j:9.3f} J  ({counter_j / elapsed:7.2f} W mean)")
+    print(f"  sampled mean:   {sampled_j:9.3f} J  ({mean_w:7.2f} W mean)")
+    print(f"  counter/sampled: {ratio:.3f}")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--seconds", type=float, default=2.0, help="comparison window")
+    ap.add_argument("--interval", type=float, default=0.1, help="power sample interval")
+    ap.add_argument("--gpu", type=int, default=None, help="probe one GPU (default: all)")
+    args = ap.parse_args()
+
+    print(f"giul-probe on {platform.node()}  ({platform.platform()})")
+    print(f"python {sys.version.split()[0]}")
+    print(f"nvidia-smi: {shutil.which('nvidia-smi') or 'not on PATH'}")
+
+    nvml = _nvml()
+    if nvml is None:
+        print("pynvml: not installed  -> no nvml_counter backend on this host")
+        if shutil.which("nvidia-smi"):
+            out = subprocess.run(
+                ["nvidia-smi", "--query-gpu=name,driver_version",
+                 "--format=csv,noheader"],
+                capture_output=True, text=True, check=False,
+            ).stdout.strip()
+            print(f"cards (via nvidia-smi):\n{out}")
+            print("-> backend smi_sampler")
+        else:
+            print("-> backend none; giul will report estimated/unknown here")
+        return
+
+    driver = nvml.nvmlSystemGetDriverVersion()
+    if isinstance(driver, bytes):
+        driver = driver.decode()
+    count = nvml.nvmlDeviceGetCount()
+    print(f"driver {driver}, {count} gpu(s)")
+
+    indices = [args.gpu] if args.gpu is not None else range(count)
+    for i in indices:
+        probe_gpu(nvml, i, args.seconds, args.interval)
+
+
+if __name__ == "__main__":
+    main()

giul-0.1.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: giul
+Version: 0.1.0
+Summary: One ruler for what an answer cost in joules, across a GPU fleet.
+Project-URL: Homepage, https://github.com/todd427/giul
+Author: Todd McCaffrey
+License-Expression: Apache-2.0
+Keywords: energy,gpu,joules,nvml,telemetry
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Provides-Extra: nvml
+Requires-Dist: nvidia-ml-py>=12.535; extra == 'nvml'
+Provides-Extra: remote
+Requires-Dist: httpx>=0.24; extra == 'remote'
+Description-Content-Type: text/markdown
+
+# giul
+
+*giúl* — Irish for joule. One ruler for "what did this answer cost in energy"
+across the FoxxeLabs fleet: Aigne, Tuiscint, Gléas.
+
+Two rulers make a comparison an argument instead of evidence. This is one,
+and all three pin it.
+
+```bash
+pip install giul              # no dependencies; imports fine with no GPU
+pip install giul[nvml]        # + nvidia-ml-py, for the energy counter
+pip install giul[remote]      # + httpx, for metering a remote node
+```
+
+## What a joule means here
+
+The number a request is charged is **energy above idle**:
+
+```
+joules = measured − idle_w × seconds
+```
+
+A request pays for the power it *caused*, not for the power the box burns
+existing. `idle_w` is supplied by the caller, per node — giul never guesses
+it, because a wrong idle floor silently rewrites every figure that node
+reports.
+
+## Three rules
+
+1. **Charged above idle.** As above.
+2. **No fabricated zeros.** A window that measured ≤ 0 J above idle did not
+   measure a free request, it failed to measure one. It degrades to
+   `estimated` (with a hint) or `unknown` — never a `sampled` zero.
+3. **Estimates are labelled as estimates.** An estimate that reads as a
+   measurement is exactly how an efficiency claim stops being evidence. A
+   sampler that cannot be reached costs a measurement, never the request.
+
+## Use
+
+```python
+from giul import Meter, Node
+
+node = Node(name="iris", gpu_index=0, idle_w=38.0,
+            is_local=True, power_endpoint=None)
+
+# async
+async with Meter.for_node(node, joules_per_1k_hint=4100.0) as m:
+    await retrieve(); m.mark("retrieve")
+    await generate(); m.mark("generate")
+e = m.result(tokens=412)
+# e.joules, e.method, e.backend, e.stages == {"retrieve": Energy, "generate": Energy}
+
+# sync
+with Meter.for_node(node, sync=torch.cuda.synchronize).sync() as m:
+    ...; m.mark("verify")
+e = m.result(tokens=n)
+```
+
+`mark(name)` closes the current stage and opens the next. The total is always
+computed over the whole window, never by summing stages, so a stage the
+sampler was too slow to see cannot corrupt it.
+
+**The caller synchronises the GPU before the closing read.** On the counter
+backend the register only counts work the card has *finished*; pass
+`sync=torch.cuda.synchronize` when the work is local. An HTTP upstream needs
+nothing — the completion returning is the sync point.
+
+## Backends
+
+Chosen at runtime in one place (`Meter.for_node`), needing no per-node
+configuration. Support is probed once per card and cached.
+
+| `backend` | when | how |
+|---|---|---|
+| `nvml_counter` | local card, `pynvml` present, counter answers | `nvmlDeviceGetTotalEnergyConsumption` delta — a true measurement of a sub-second window |
+| `smi_sampler` | local card, `nvidia-smi` on PATH | integral of `power.draw` samples |
+| `remote_agent` | `node.power_endpoint` set | the same integral, sampled by `giul-agent` on that node |
+| `none` | otherwise | `estimated` with a hint, else `unknown` |
+
+`method` stays `sampled` / `estimated` / `unknown`. The counter *is* a
+measurement, so it reports `method="sampled"`; the distinction lives in
+`backend`.
+
+## Tools
+
+```bash
+giul-probe                    # what this host's cards support; counter vs sampler
+giul-agent --port 9402        # expose a node's power draw; stdlib only, read-only
+```
+
+Bind `giul-agent` to the mesh address, not `0.0.0.0`, unless the node is
+otherwise firewalled.
+
+## Not in 0.1
+
+CPU/RAPL, carbon, € cost, storing series, any UI.

giul-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+giul/__init__.py,sha256=eFtyR3SqY_pnFGCvj03Qu_Hu6IAIKikm0YufLk01oNc,1343
+giul/agent.py,sha256=AxfTuNybNr0D_h2vuzW_9x2rXrd0kJAJWpkz9d--d_g,3818
+giul/backends.py,sha256=SrWfybPepJorm8MPnPzP-wQsFB_-IMOCfQk1XAlO-vQ,7499
+giul/meter.py,sha256=F2TZW6ZGcmS1KDfdTP2AZiDSnjqjHffWKr4ZDi17cYc,15107
+giul/probe.py,sha256=aAnacXsUp2aBZZwQoIFIJBU7OdjvYuB0pUYlzwX-iqI,4866
+giul-0.1.0.dist-info/METADATA,sha256=CvuYSatIRC6n0RPGjD6JZ54UI9CpOvF6_AE9ixhHTvI,4120
+giul-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+giul-0.1.0.dist-info/entry_points.txt,sha256=FFD-JPRL56kAHbj5uSb9bmNO-OZ2pU69jReoTwC-15g,76
+giul-0.1.0.dist-info/RECORD,,

giul-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

giul-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+giul-agent = giul.agent:main
+giul-probe = giul.probe:main