gpu-gate 0.2.0__py3-none-any.whl

gpu_gate/__init__.py

@@ -0,0 +1,15 @@
+"""gpu-gate: wait for a free GPU, claim it, and run a command on it."""
+
+from gpu_gate.models import GpuStatus, Requirements, Selection
+from gpu_gate.selector import NotEnoughGPUs, select
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "GpuStatus",
+    "NotEnoughGPUs",
+    "Requirements",
+    "Selection",
+    "__version__",
+    "select",
+]

gpu_gate/__main__.py

@@ -0,0 +1,4 @@
+from gpu_gate.cli import entrypoint
+
+if __name__ == "__main__":
+    entrypoint()

gpu_gate/cli.py

@@ -0,0 +1,213 @@
+"""Command-line interface for gpu-gate."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from gpu_gate import __version__
+from gpu_gate.models import GpuStatus, Requirements
+from gpu_gate.probe import NvmlProbe, Probe, ProbeError
+from gpu_gate.runner import (
+    WaitConfig,
+    WaitTimeout,
+    run_with_gpus,
+    wait_for_selection,
+)
+from gpu_gate.selector import NotEnoughGPUs
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="Wait for a free GPU, claim it, and run a command on it.",
+)
+_err = Console(stderr=True)
+_out = Console()
+
+EXIT_OK = 0
+EXIT_TIMEOUT = 124
+EXIT_NO_GPU = 3
+EXIT_PROBE = 4
+
+
+def _requirements(
+    count: int,
+    min_free_mb: int,
+    max_util: int,
+    exclude: str | None,
+    only: str | None,
+) -> Requirements:
+    return Requirements(
+        count=count,
+        min_free_mb=min_free_mb,
+        max_utilization_pct=max_util,
+        exclude=_parse_indices(exclude),
+        include=_parse_indices(only) if only else None,
+    )
+
+
+def _parse_indices(value: str | None) -> frozenset[int]:
+    if not value:
+        return frozenset()
+    out: set[int] = set()
+    for chunk in value.split(","):
+        chunk = chunk.strip()
+        if chunk:
+            out.add(int(chunk))
+    return frozenset(out)
+
+
+def _make_probe() -> Probe:
+    return NvmlProbe()
+
+
+def _status_rows(statuses: list[GpuStatus]) -> Table:
+    table = Table(box=None, pad_edge=False)
+    table.add_column("idx", justify="right")
+    table.add_column("name")
+    table.add_column("free", justify="right")
+    table.add_column("total", justify="right")
+    table.add_column("util", justify="right")
+    for s in statuses:
+        table.add_row(
+            str(s.index),
+            s.name,
+            f"{s.memory_free_mb} MiB",
+            f"{s.memory_total_mb} MiB",
+            f"{s.utilization_pct}%",
+        )
+    return table
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        _out.print(f"gpu-gate {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    _version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the version and exit.",
+    ),
+) -> None:
+    """gpu-gate command-line interface."""
+
+
+@app.command("status")
+def status(
+    as_json: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
+) -> None:
+    """Show the current state of every visible GPU."""
+
+    try:
+        statuses = _make_probe().query()
+    except ProbeError as exc:
+        _err.print(f"gpu-gate: {exc}")
+        raise typer.Exit(EXIT_PROBE) from exc
+    if as_json:
+        payload = [
+            {
+                "index": s.index,
+                "name": s.name,
+                "uuid": s.uuid,
+                "memory_total_mb": s.memory_total_mb,
+                "memory_used_mb": s.memory_used_mb,
+                "memory_free_mb": s.memory_free_mb,
+                "utilization_pct": s.utilization_pct,
+            }
+            for s in statuses
+        ]
+        _out.print_json(json.dumps(payload))
+    else:
+        _out.print(_status_rows(statuses))
+
+
+@app.command("wait")
+def wait(
+    count: int = typer.Option(1, "-n", "--count", help="Number of GPUs to wait for."),
+    min_free_mb: int = typer.Option(0, "--min-free-mb", help="Minimum free memory."),
+    max_util: int = typer.Option(100, "--max-util", help="Maximum utilization percent."),
+    exclude: str | None = typer.Option(None, "--exclude", help="Indices to skip, e.g. 0,1."),
+    only: str | None = typer.Option(None, "--only", help="Restrict to these indices."),
+    poll: float = typer.Option(5.0, "--poll", help="Seconds between polls."),
+    timeout: float | None = typer.Option(None, "--timeout", help="Give up after N seconds."),
+    as_json: bool = typer.Option(False, "--json", help="Print the chosen indices as JSON."),
+) -> None:
+    """Block until enough GPUs are free, then print the chosen indices."""
+
+    req = _requirements(count, min_free_mb, max_util, exclude, only)
+    config = WaitConfig(requirements=req, poll_interval=poll, timeout=timeout)
+    try:
+        selection = wait_for_selection(_make_probe(), config)
+    except WaitTimeout as exc:
+        _err.print(f"gpu-gate: {exc}")
+        raise typer.Exit(EXIT_TIMEOUT) from exc
+    except ProbeError as exc:
+        _err.print(f"gpu-gate: {exc}")
+        raise typer.Exit(EXIT_PROBE) from exc
+    if as_json:
+        _out.print_json(json.dumps({"indices": list(selection.indices)}))
+    else:
+        _out.print(selection.cuda_visible_devices)
+
+
+@app.command(
+    "run",
+    context_settings={"allow_extra_args": True, "ignore_unknown_options": True},
+)
+def run(
+    ctx: typer.Context,
+    count: int = typer.Option(1, "-n", "--count", help="Number of GPUs to claim."),
+    min_free_mb: int = typer.Option(0, "--min-free-mb", help="Minimum free memory."),
+    max_util: int = typer.Option(100, "--max-util", help="Maximum utilization percent."),
+    exclude: str | None = typer.Option(None, "--exclude", help="Indices to skip."),
+    only: str | None = typer.Option(None, "--only", help="Restrict to these indices."),
+    poll: float = typer.Option(5.0, "--poll", help="Seconds between polls."),
+    timeout: float | None = typer.Option(None, "--timeout", help="Give up after N seconds."),
+    quiet: bool = typer.Option(False, "--quiet", help="Do not announce the choice."),
+) -> None:
+    """Wait for GPUs, set CUDA_VISIBLE_DEVICES, and run COMMAND.
+
+    Put the command after a literal ``--``, for example:
+
+        gpu-gate run -n 1 --min-free-mb 8000 -- python train.py
+    """
+
+    command = list(ctx.args)
+    if not command:
+        _err.print("gpu-gate: no command given; pass it after --")
+        raise typer.Exit(2)
+
+    req = _requirements(count, min_free_mb, max_util, exclude, only)
+    config = WaitConfig(requirements=req, poll_interval=poll, timeout=timeout)
+
+    def announce(_exc: NotEnoughGPUs) -> None:
+        if not quiet:
+            _err.print("gpu-gate: waiting for a free GPU ...")
+
+    try:
+        code = run_with_gpus(_make_probe(), config, command, on_wait=announce)
+    except WaitTimeout as exc:
+        _err.print(f"gpu-gate: {exc}")
+        raise typer.Exit(EXIT_TIMEOUT) from exc
+    except ProbeError as exc:
+        _err.print(f"gpu-gate: {exc}")
+        raise typer.Exit(EXIT_PROBE) from exc
+    raise typer.Exit(code)
+
+
+def entrypoint() -> None:
+    try:
+        app()
+    except KeyboardInterrupt:  # pragma: no cover - interactive only
+        print("gpu-gate: interrupted", file=sys.stderr)
+        raise SystemExit(130) from None

gpu_gate/lock.py

@@ -0,0 +1,72 @@
+"""Cooperative, host-local locks so two gpu-gate runs do not grab the same
+just-freed card.
+
+A lock is a small file under a shared directory (``$GPU_GATE_LOCK_DIR`` or a
+per-user default). Holding the lock means "I am about to use this GPU";
+selection skips devices whose lock is currently held by a live process.
+The scheme is advisory: it only coordinates other gpu-gate callers, not
+arbitrary CUDA programs.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from contextlib import ExitStack
+from pathlib import Path
+
+from filelock import FileLock, Timeout
+
+
+def lock_dir() -> Path:
+    env = os.environ.get("GPU_GATE_LOCK_DIR")
+    if env:
+        path = Path(env)
+    else:
+        base = os.environ.get("XDG_RUNTIME_DIR") or tempfile.gettempdir()
+        path = Path(base) / "gpu-gate-locks"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def _lock_path(index: int) -> Path:
+    return lock_dir() / f"gpu{index}.lock"
+
+
+def is_locked(index: int) -> bool:
+    """Return whether GPU ``index`` is currently claimed by another caller."""
+
+    lock = FileLock(str(_lock_path(index)), timeout=0)
+    try:
+        lock.acquire()
+    except Timeout:
+        return True
+    else:
+        lock.release()
+        return False
+
+
+class GpuClaim:
+    """Hold locks for a set of GPU indices for the lifetime of the context."""
+
+    def __init__(self, indices: tuple[int, ...]) -> None:
+        self.indices = indices
+        self._stack: ExitStack | None = None
+
+    def __enter__(self) -> GpuClaim:
+        stack = ExitStack()
+        try:
+            for index in self.indices:
+                lock = FileLock(str(_lock_path(index)), timeout=0)
+                lock.acquire()
+                stack.callback(lock.release)
+        except Timeout:
+            stack.close()
+            raise
+        self._stack = stack
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        if self._stack is not None:
+            self._stack.close()
+            self._stack = None

gpu_gate/models.py

@@ -0,0 +1,61 @@
+"""Plain data structures shared across gpu-gate.
+
+These types carry no behaviour and no NVML dependency, which keeps the
+selection logic in :mod:`gpu_gate.selector` pure and trivially testable.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True)
+class GpuStatus:
+    """A point-in-time snapshot of a single GPU."""
+
+    index: int
+    name: str
+    uuid: str
+    memory_total_mb: int
+    memory_used_mb: int
+    utilization_pct: int
+
+    @property
+    def memory_free_mb(self) -> int:
+        return max(0, self.memory_total_mb - self.memory_used_mb)
+
+    @property
+    def memory_used_pct(self) -> float:
+        if self.memory_total_mb <= 0:
+            return 0.0
+        return 100.0 * self.memory_used_mb / self.memory_total_mb
+
+
+@dataclass(frozen=True, slots=True)
+class Requirements:
+    """What a caller needs before a GPU is considered usable."""
+
+    count: int = 1
+    min_free_mb: int = 0
+    max_utilization_pct: int = 100
+    exclude: frozenset[int] = field(default_factory=frozenset)
+    include: frozenset[int] | None = None
+
+    def __post_init__(self) -> None:
+        if self.count < 1:
+            raise ValueError("count must be >= 1")
+        if self.min_free_mb < 0:
+            raise ValueError("min_free_mb must be >= 0")
+        if not 0 <= self.max_utilization_pct <= 100:
+            raise ValueError("max_utilization_pct must be between 0 and 100")
+
+
+@dataclass(frozen=True, slots=True)
+class Selection:
+    """The result of a successful selection."""
+
+    indices: tuple[int, ...]
+
+    @property
+    def cuda_visible_devices(self) -> str:
+        return ",".join(str(i) for i in self.indices)

gpu_gate/probe.py

@@ -0,0 +1,92 @@
+"""Read GPU state from the system.
+
+The real implementation talks to NVIDIA's NVML through ``pynvml``. NVML is
+imported lazily so the package installs and imports on machines without a
+driver; the dependency only matters when you actually probe hardware.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from gpu_gate.models import GpuStatus
+
+
+class Probe(Protocol):
+    """Anything that can report the current state of the local GPUs."""
+
+    def query(self) -> list[GpuStatus]: ...
+
+
+class ProbeError(RuntimeError):
+    """Raised when GPU state cannot be read."""
+
+
+class NvmlProbe:
+    """Query local NVIDIA GPUs via NVML.
+
+    A single instance keeps NVML initialized between calls; use it as a
+    context manager (or call :meth:`close`) to release the handle.
+    """
+
+    def __init__(self) -> None:
+        self._nvml = None
+
+    def _ensure_init(self):
+        if self._nvml is not None:
+            return self._nvml
+        try:
+            import pynvml
+        except ImportError as exc:  # pragma: no cover - import guard
+            raise ProbeError(
+                "pynvml is not installed; install gpu-gate with its default "
+                "dependencies to read GPU state"
+            ) from exc
+        try:
+            pynvml.nvmlInit()
+        except Exception as exc:  # pragma: no cover - needs a driver
+            raise ProbeError("could not initialize NVML; is an NVIDIA driver present?") from exc
+        self._nvml = pynvml
+        return pynvml
+
+    def query(self) -> list[GpuStatus]:
+        pynvml = self._ensure_init()
+        out: list[GpuStatus] = []
+        count = pynvml.nvmlDeviceGetCount()
+        for index in range(count):
+            handle = pynvml.nvmlDeviceGetHandleByIndex(index)
+            mem = pynvml.nvmlDeviceGetMemoryInfo(handle)
+            util = pynvml.nvmlDeviceGetUtilizationRates(handle)
+            out.append(
+                GpuStatus(
+                    index=index,
+                    name=_as_text(pynvml.nvmlDeviceGetName(handle)),
+                    uuid=_as_text(pynvml.nvmlDeviceGetUUID(handle)),
+                    memory_total_mb=int(mem.total // (1024 * 1024)),
+                    memory_used_mb=int(mem.used // (1024 * 1024)),
+                    utilization_pct=int(util.gpu),
+                )
+            )
+        return out
+
+    def close(self) -> None:
+        if self._nvml is not None:
+            try:
+                self._nvml.nvmlShutdown()
+            finally:
+                self._nvml = None
+
+    def __enter__(self) -> NvmlProbe:
+        self._ensure_init()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+def _as_text(value: object) -> str:
+    """NVML returns ``bytes`` on some versions and ``str`` on others."""
+
+    if isinstance(value, bytes):
+        return value.decode("utf-8", "replace")
+    return str(value)

gpu_gate/runner.py

@@ -0,0 +1,109 @@
+"""Wait for eligible GPUs, claim them, and hand control to the command.
+
+The wait loop takes its clock and sleep function as arguments so tests can
+drive timeouts deterministically without real delays.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+
+from gpu_gate.lock import GpuClaim, is_locked
+from gpu_gate.models import GpuStatus, Requirements, Selection
+from gpu_gate.probe import Probe
+from gpu_gate.selector import NotEnoughGPUs, select
+
+Clock = Callable[[], float]
+Sleep = Callable[[float], None]
+
+
+class WaitTimeout(Exception):
+    """Raised when no eligible GPU appeared before the deadline."""
+
+    def __init__(self, seconds: float) -> None:
+        self.seconds = seconds
+        super().__init__(f"timed out after {seconds:g}s waiting for a free GPU")
+
+
+@dataclass(frozen=True, slots=True)
+class WaitConfig:
+    requirements: Requirements
+    poll_interval: float = 5.0
+    timeout: float | None = None
+    respect_locks: bool = True
+
+
+def _without_locked(statuses: Sequence[GpuStatus]) -> list[GpuStatus]:
+    return [s for s in statuses if not is_locked(s.index)]
+
+
+def wait_for_selection(
+    probe: Probe,
+    config: WaitConfig,
+    *,
+    clock: Clock = time.monotonic,
+    sleep: Sleep = time.sleep,
+    on_wait: Callable[[NotEnoughGPUs], None] | None = None,
+) -> Selection:
+    """Poll ``probe`` until ``config.requirements`` can be met, then return it.
+
+    Raises :class:`WaitTimeout` if a timeout is set and elapses first.
+    """
+
+    start = clock()
+    while True:
+        statuses = probe.query()
+        if config.respect_locks:
+            statuses = _without_locked(statuses)
+        try:
+            return select(statuses, config.requirements)
+        except NotEnoughGPUs as exc:
+            if on_wait is not None:
+                on_wait(exc)
+            if config.timeout is not None and clock() - start >= config.timeout:
+                raise WaitTimeout(config.timeout) from exc
+            sleep(config.poll_interval)
+
+
+def build_child_env(selection: Selection, base: dict[str, str] | None = None) -> dict[str, str]:
+    """Return an environment with ``CUDA_VISIBLE_DEVICES`` set to the choice."""
+
+    env = dict(os.environ if base is None else base)
+    env["CUDA_VISIBLE_DEVICES"] = selection.cuda_visible_devices
+    return env
+
+
+def run_with_gpus(
+    probe: Probe,
+    config: WaitConfig,
+    command: Sequence[str],
+    *,
+    clock: Clock = time.monotonic,
+    sleep: Sleep = time.sleep,
+    exec_fn: Callable[[Sequence[str], dict[str, str]], int] | None = None,
+    on_wait: Callable[[NotEnoughGPUs], None] | None = None,
+) -> int:
+    """Wait for GPUs, claim them, and run ``command``. Returns its exit code."""
+
+    if not command:
+        raise ValueError("command must not be empty")
+    selection = wait_for_selection(probe, config, clock=clock, sleep=sleep, on_wait=on_wait)
+    runner = exec_fn or _spawn
+    with GpuClaim(selection.indices):
+        env = build_child_env(selection)
+        return runner(command, env)
+
+
+def _spawn(command: Sequence[str], env: dict[str, str]) -> int:
+    import subprocess
+
+    try:
+        completed = subprocess.run(list(command), env=env, check=False)  # noqa: S603
+    except FileNotFoundError:
+        print(f"gpu-gate: command not found: {command[0]}", file=sys.stderr)
+        return 127
+    return completed.returncode

gpu_gate/selector.py

@@ -0,0 +1,61 @@
+"""Pure GPU selection logic.
+
+Given a list of :class:`~gpu_gate.models.GpuStatus` and a set of
+:class:`~gpu_gate.models.Requirements`, decide which devices to claim.
+No NVML, no I/O, no global state, so it can be exercised exhaustively
+in unit tests without a GPU present.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from gpu_gate.models import GpuStatus, Requirements, Selection
+
+
+class NotEnoughGPUs(Exception):
+    """Raised when fewer GPUs meet the requirements than were requested."""
+
+    def __init__(self, requested: int, available: int) -> None:
+        self.requested = requested
+        self.available = available
+        super().__init__(f"requested {requested} GPU(s) but only {available} met the requirements")
+
+
+def eligible(status: GpuStatus, req: Requirements) -> bool:
+    """Return whether a single GPU satisfies the requirements."""
+
+    if req.include is not None and status.index not in req.include:
+        return False
+    if status.index in req.exclude:
+        return False
+    if status.memory_free_mb < req.min_free_mb:
+        return False
+    if status.utilization_pct > req.max_utilization_pct:
+        return False
+    return True
+
+
+def rank(statuses: Iterable[GpuStatus]) -> list[GpuStatus]:
+    """Order GPUs best-first: most free memory, then lowest utilization.
+
+    Index is the final tie-breaker so the ordering is deterministic.
+    """
+
+    return sorted(
+        statuses,
+        key=lambda s: (-s.memory_free_mb, s.utilization_pct, s.index),
+    )
+
+
+def select(statuses: Iterable[GpuStatus], req: Requirements) -> Selection:
+    """Choose ``req.count`` GPUs that satisfy ``req``.
+
+    Raises :class:`NotEnoughGPUs` if not enough eligible devices exist.
+    """
+
+    candidates = rank(s for s in statuses if eligible(s, req))
+    if len(candidates) < req.count:
+        raise NotEnoughGPUs(requested=req.count, available=len(candidates))
+    chosen = candidates[: req.count]
+    return Selection(indices=tuple(sorted(s.index for s in chosen)))

gpu_gate-0.2.0.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: gpu-gate
+Version: 0.2.0
+Summary: Wait for a free GPU, claim it, and run a command on it.
+Project-URL: Homepage, https://github.com/jmweb-org/gpu-gate
+Project-URL: Repository, https://github.com/jmweb-org/gpu-gate
+Project-URL: Issues, https://github.com/jmweb-org/gpu-gate/issues
+Author: José del Río
+License: MIT License
+        
+        Copyright (c) 2026 José del Río
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cli,cuda,gpu,nvidia,nvml,scheduler
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: GPU :: NVIDIA CUDA
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: filelock>=3.12
+Requires-Dist: nvidia-ml-py>=12.535
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# gpu-gate
+
+[![CI](https://github.com/jmweb-org/gpu-gate/actions/workflows/ci.yml/badge.svg)](https://github.com/jmweb-org/gpu-gate/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/gpu-gate.svg)](https://pypi.org/project/gpu-gate/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Wait for a free GPU, claim it, set `CUDA_VISIBLE_DEVICES`, and run your command.
+
+On a shared multi-GPU box without a cluster scheduler, starting a job usually
+means watching `nvidia-smi`, picking a card by hand, exporting the env var, and
+remembering to actually launch. `gpu-gate` is the small wait-pick-export-run
+loop that does this for you, with a cooperative lock so two invocations on the
+same host do not grab the same just-freed card. No daemon, no server, nothing
+to administer.
+
+```console
+$ gpu-gate run --min-free-mb 8000 -- python train.py
+gpu-gate: waiting for a free GPU ...
+# ... blocks until a card has >= 8 GB free, then runs train.py with
+# CUDA_VISIBLE_DEVICES set to the chosen index
+```
+
+## Install
+
+```console
+$ pip install gpu-gate                 # from PyPI, once released
+$ pip install git+https://github.com/jmweb-org/gpu-gate   # latest, available now
+```
+
+It requires an NVIDIA driver at run time. The NVML binding
+(`nvidia-ml-py`) is pulled in automatically; the package still installs and
+imports on machines without a GPU, so it is safe to add to shared requirements.
+
+## Usage
+
+### Run a command on a free GPU
+
+```console
+$ gpu-gate run -n 1 --min-free-mb 8000 -- python train.py --epochs 50
+```
+
+Everything after `--` is the command. `gpu-gate` blocks until the requirements
+are met, claims the chosen device(s), exports `CUDA_VISIBLE_DEVICES`, and execs
+the command. Its own exit code is the command's exit code, so it drops cleanly
+into scripts and CI.
+
+Common options:
+
+| Option | Meaning |
+| --- | --- |
+| `-n, --count` | Number of GPUs to claim (default 1) |
+| `--min-free-mb` | Require at least this much free memory |
+| `--max-util` | Skip cards busier than this percent |
+| `--only 0,1` | Restrict the search to these indices |
+| `--exclude 2,3` | Never pick these indices |
+| `--poll` | Seconds between checks (default 5) |
+| `--timeout` | Give up after N seconds (exit 124) |
+
+### Just wait, then use the result yourself
+
+```console
+$ export CUDA_VISIBLE_DEVICES=$(gpu-gate wait --min-free-mb 8000)
+```
+
+### Inspect the current state
+
+```console
+$ gpu-gate status
+idx  name           free        total       util
+  0  NVIDIA L40S    44211 MiB   46068 MiB    3%
+  1  NVIDIA L40S      812 MiB   46068 MiB   97%
+
+$ gpu-gate status --json
+```
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Command ran (its own code is forwarded) |
+| 2 | Bad invocation (for example, no command after `--`) |
+| 124 | Timed out waiting for a GPU |
+| 3 | Requirements could never be met |
+| 4 | Could not read GPU state (no driver / NVML error) |
+
+## How selection works
+
+A GPU is eligible when it has enough free memory, is below the utilization
+ceiling, is not excluded, and is not currently locked by another `gpu-gate`
+caller. Eligible cards are ranked by most free memory, then lowest
+utilization, then index, and the top `--count` are chosen. The ordering is
+fully deterministic.
+
+## Locking
+
+While a command runs, `gpu-gate` holds an advisory file lock per claimed
+device under `$GPU_GATE_LOCK_DIR` (a per-user directory by default). Other
+`gpu-gate` invocations skip locked devices, which avoids the classic race where
+two jobs both see the same card free at the same instant. The lock is advisory:
+it coordinates `gpu-gate` callers, not arbitrary CUDA programs.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

gpu_gate-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+gpu_gate/__init__.py,sha256=aheQ9bzv_7YxyEay-6KgLe-jlqHvW8tJ6VY3TSNi4OM,334
+gpu_gate/__main__.py,sha256=-K0PP9Dejd0YsIKDNGCSVQizMGx1-YYAAE0DGp9q7x8,81
+gpu_gate/cli.py,sha256=ELdGznx1BPq_rzzP3NZrMVQhvgXMIlqUAIpYEgLS_R8,6687
+gpu_gate/lock.py,sha256=B96J2K5hHWMxXbWCggOC8wt2HdYjLwjEFRp_VfrK8Bw,2008
+gpu_gate/models.py,sha256=WggqmEYyNjltLVABwFccbE50E-y04l1TFl7-jiG5e7I,1691
+gpu_gate/probe.py,sha256=rmV-PPSgFMatxDTN_SAnhxGTjYEgb95oNVJ3AyYqE54,2880
+gpu_gate/runner.py,sha256=Lkv6MtaTLh1lGfrXSUeWBaANjwo3sHhAhkhkzWEGRrQ,3429
+gpu_gate/selector.py,sha256=RYcigKR_ZgC3LSvMILEi1v6LDE_GyRvVI937SXeuDog,2021
+gpu_gate-0.2.0.dist-info/METADATA,sha256=jZVdkWP7PXozFatELomuJG2LmCSsfBgGCcEsJ9r7p50,6050
+gpu_gate-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+gpu_gate-0.2.0.dist-info/entry_points.txt,sha256=mR4F0k-HdSWtzhVUc9Q4iwkMQIxuabiTjICD5jBDaN0,53
+gpu_gate-0.2.0.dist-info/licenses/LICENSE,sha256=N4nJy_wSxYwULjDvuE2GupQWZSSwgOOU_HJSzuxHBsI,1071
+gpu_gate-0.2.0.dist-info/RECORD,,

gpu_gate-0.2.0.dist-info/WHEEL

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

gpu_gate-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gpu-gate = gpu_gate.cli:entrypoint

gpu_gate-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 José del Río
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.