gpu-gate 0.2.0__tar.gz

gpu_gate-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Sync dependencies
+        run: uv sync --all-extras --dev
+      - name: Lint
+        run: uv run ruff check .
+      - name: Format check
+        run: uv run ruff format --check .
+      - name: Test
+        run: uv run pytest --cov --cov-report=term-missing

gpu_gate-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        run: uv publish

gpu_gate-0.2.0/.gitignore

@@ -0,0 +1,26 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+
+# uv
+uv.lock
+
+# Test and coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.ruff_cache/
+
+# Editor / OS
+.vscode/
+.idea/
+.DS_Store

gpu_gate-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,15 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.9
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict

gpu_gate-0.2.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based
+on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-05-10
+
+### Added
+- Docker image and a published container entry point.
+- Continuous integration across Python 3.10, 3.11 and 3.12 (lint, format
+  check and tests).
+- Expanded documentation and usage examples.
+
+### Changed
+- Hardened packaging metadata and pinned the supported Python versions.
+
+## [0.1.0] - 2026-05-07
+
+### Added
+- `run` command: wait for a free GPU, claim it with a cooperative lock, set
+  `CUDA_VISIBLE_DEVICES`, and exec the wrapped command.
+- `wait` command: block until a GPU is free and print the chosen index.
+- `status` command: list visible GPUs with free memory and utilization, with
+  optional JSON output.
+- Filters for memory, utilization and explicit index include/exclude.
+- Advisory per-device file locks to avoid two runs grabbing the same card.
+
+[0.2.0]: https://github.com/jmweb-org/gpu-gate/releases/tag/v0.2.0
+[0.1.0]: https://github.com/jmweb-org/gpu-gate/releases/tag/v0.1.0

gpu_gate-0.2.0/Dockerfile

@@ -0,0 +1,20 @@
+# gpu-gate runs on the host's NVIDIA driver via NVML. Build a small image and
+# run it with `--gpus all` so the container can see the cards:
+#
+#   docker build -t gpu-gate .
+#   docker run --rm --gpus all gpu-gate status
+#
+FROM python:3.12-slim
+
+LABEL org.opencontainers.image.source="https://github.com/jmweb-org/gpu-gate"
+LABEL org.opencontainers.image.description="Wait for a free GPU, claim it, and run a command on it."
+LABEL org.opencontainers.image.licenses="MIT"
+
+WORKDIR /app
+COPY pyproject.toml README.md LICENSE ./
+COPY src ./src
+
+RUN pip install --no-cache-dir .
+
+ENTRYPOINT ["gpu-gate"]
+CMD ["--help"]

gpu_gate-0.2.0/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.

gpu_gate-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,105 @@
+# 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/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gpu-gate"
+version = "0.2.0"
+description = "Wait for a free GPU, claim it, and run a command on it."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [{ name = "José del Río" }]
+keywords = ["gpu", "cuda", "nvidia", "nvml", "scheduler", "cli"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: GPU :: NVIDIA CUDA",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Distributed Computing",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.0",
+    "filelock>=3.12",
+    "nvidia-ml-py>=12.535",
+]
+
+[project.urls]
+Homepage = "https://github.com/jmweb-org/gpu-gate"
+Repository = "https://github.com/jmweb-org/gpu-gate"
+Issues = "https://github.com/jmweb-org/gpu-gate/issues"
+
+[project.scripts]
+gpu-gate = "gpu_gate.cli:entrypoint"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gpu_gate"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "S", "C4", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101"]
+
+[tool.coverage.run]
+source = ["gpu_gate"]
+branch = true

gpu_gate-0.2.0/src/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-0.2.0/src/gpu_gate/__main__.py

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