gq-local 0.1.1__tar.gz

gq_local-0.1.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,58 @@
+name: Bug report
+description: Something in gq behaves incorrectly
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Before filing, please check
+        [docs/troubleshooting.md](https://github.com/BirddWang/gq/blob/main/docs/troubleshooting.md)
+        — GPUs stuck in `EXTERNAL`/`UNKNOWN`, jobs stuck in `WAITING`, and daemon
+        startup failures are covered there.
+
+        **Do not attach `gq.sqlite3`.** It stores the environment of every job.
+        Skim the daemon log before pasting it: it records job commands and paths.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What did you expect, and what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. gq -g 1 ...
+        2. gq ps
+        3. ...
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: gq version
+      description: Output of `gq --version`
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: Linux distribution, Python version, NVIDIA driver version, and whether you run in a container
+      placeholder: "Ubuntu 24.04, Python 3.12, driver 560.35, inside Docker"
+    validations:
+      required: true
+  - type: textarea
+    id: state
+    attributes:
+      label: Scheduler state
+      description: Output of `gq gpu` and `gq ps`, plus `gq show JOB` if one job is involved
+      render: text
+  - type: textarea
+    id: daemon-log
+    attributes:
+      label: Daemon log
+      description: Relevant lines from `tail -n 100 ~/.local/share/gq/gq-daemon.log`
+      render: text

gq_local-0.1.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/BirddWang/gq/security/advisories/new
+    about: Please report vulnerabilities privately, not as a public issue.

gq_local-0.1.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,29 @@
+name: Feature request
+description: Suggest something gq should do
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        `gq` is deliberately small, and some things are permanent non-goals:
+        multi-node scheduling, CPU/RAM allocation, MIG, and fractional GPU sharing.
+        See [CONTRIBUTING.md](https://github.com/BirddWang/gq/blob/main/CONTRIBUTING.md#scope).
+
+        Please open an issue before writing the code, so a rejected PR does not
+        waste your time.
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What are you trying to do that gq makes hard today? Describe the situation, not the solution.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you have in mind
+      description: If you have a specific interface in mind, sketch it.
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What you do instead today

gq_local-0.1.1/.github/pull_request_template.md

@@ -0,0 +1,18 @@
+## What this changes
+
+<!-- And why. Link the issue it addresses, if there is one. -->
+
+## Checklist
+
+- [ ] `uv run pytest` passes
+- [ ] `uv run ruff check .` and `uv run mypy` pass
+- [ ] Tests cover the change
+- [ ] `CHANGELOG.md` updated under `## [Unreleased]`, if behavior changed
+- [ ] `docs/` updated, if the interface changed
+- [ ] Schema change appends a migration and bumps `SCHEMA_VERSION` (see CONTRIBUTING.md)
+- [ ] IPC change bumps `PROTOCOL_VERSION`, if it is not backward compatible
+
+## Allocation safety
+
+<!-- Delete if this does not touch allocation, cancellation, or recovery.
+     Otherwise: which invariant does this rely on, and what test shows it holds? -->

gq_local-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: pytest (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Install
+        run: uv sync --all-groups --python ${{ matrix.python-version }}
+      - name: Test
+        # The suite runs against a fake NVML provider, so no GPU is needed. The
+        # hardware tests under tests/integration stay opt-in via GQ_RUN_GPU_TESTS.
+        run: uv run pytest
+
+  lint:
+    name: ruff and mypy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Install
+        run: uv sync --all-groups
+      - name: Ruff
+        run: uv run ruff check .
+      - name: Ruff format check
+        run: uv run ruff format --check .
+      - name: Mypy
+        run: uv run mypy
+
+  build:
+    name: build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build
+        run: uv build
+      - name: Check metadata
+        run: uvx twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/

gq_local-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,50 @@
+name: Release
+
+# Publishes to PyPI when a version tag is pushed. Authentication uses PyPI trusted
+# publishing (OIDC), so no API token is stored in the repository.
+#
+# One-time setup at https://pypi.org/manage/account/publishing/ :
+#   PyPI project name: gq-local
+#   Owner:             BirddWang
+#   Repository:        gq
+#   Workflow:          release.yml
+#   Environment:       pypi
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - name: Fail if the tag and the package version disagree
+        run: |
+          version="$(uv run python -c 'import gq; print(gq.__version__)')"
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "$version" != "$tag" ]; then
+            echo "tag $tag does not match gq.__version__ $version" >&2
+            exit 1
+          fi
+        if: startsWith(github.ref, 'refs/tags/')
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

gq_local-0.1.1/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+.pytest_cache/
+__pycache__/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+
+.ruff_cache/
+.mypy_cache/

gq_local-0.1.1/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to this project are documented here. This project follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2026-09-10
+
+A hardening release. No new scheduling behavior; everything here came from defects
+and rough edges observed in the first week of real use.
+
+### Fixed
+
+- The daemon no longer logs a traceback every time a client hangs up mid-response.
+  `gq ps | head` and Ctrl-C out of `gq logs -f` are ordinary events, but each one
+  raised `ConnectionResetError`/`BrokenPipeError` out of the connection callback.
+- Running as root inside a container is now allowed without `GQ_ALLOW_ROOT=1`.
+  Docker and Jupyter images commonly have uid 0 as the only account, and the guard
+  made `gq` unusable there. It still refuses on what looks like a regular host, where
+  the warning is genuinely warranted.
+- `PRAGMA foreign_keys = ON` is now issued as its own statement rather than inside
+  the schema script, so `ON DELETE CASCADE` on `job_gpus` cannot silently be a no-op.
+
+### Added
+
+- **Schema migrations.** The database carries a `PRAGMA user_version` and applies
+  ordered migrations, each in one transaction with its version bump. Databases
+  created before this release are adopted in place, not rebuilt.
+- **`gq rm JOB...`** deletes terminal jobs and their logs. Active jobs are refused,
+  and one bad id rejects the whole batch rather than partially destroying history.
+- **`gq clean --older-than AGE [--state STATE] [-y]`** sweeps old terminal jobs and
+  their logs. Defaults to 30d and confirms before deleting.
+- **`--json`** on `gq ps`, `gq gpu`, and `gq show`.
+- **Protocol versioning.** Every request carries a protocol number; a mismatched
+  daemon reports how to restart instead of failing on a missing field. `gq daemon
+  status` warns when the running daemon predates the installed client.
+
+### Changed
+
+- **Secret-looking environment variables are no longer persisted by default.** The
+  submission environment is stored verbatim in SQLite so queued jobs survive a daemon
+  restart, which made every captured credential a durable one. Variables matching
+  `TOKEN`, `SECRET`, `PASSWORD`, `CREDENTIAL`, `*_KEY`, `API_KEY` or the `AWS_`,
+  `AZURE_`, `GCP_`, `GOOGLE_APPLICATION_` prefixes are dropped, and the dropped names
+  are printed at submit time rather than being removed silently.
+
+  This is a **behavior change that can break jobs** which need a credential at
+  runtime — `HF_TOKEN` for a private Hugging Face dataset, for instance. Restore the
+  old behavior per-job with `--env-all`, globally with `GQ_ENV_ALL=1`, or for one
+  variable with `--env-keep HF_TOKEN`.
+
+## [0.1.0] - 2026-08-31
+
+Initial MVP: queueing, atomic NVML-checked GPU allocation, `CUDA_VISIBLE_DEVICES`
+assignment, detached execution, cancellation, and crash/reboot recovery.

gq_local-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,123 @@
+# Contributing to gq
+
+Thanks for taking a look. `gq` is deliberately small, and the bar for adding to it is
+correspondingly high — please read "Scope" before starting on a feature.
+
+## Getting set up
+
+```bash
+git clone https://github.com/BirddWang/gq
+cd gq
+uv sync --all-groups
+uv run pytest
+```
+
+Most of the suite runs against a fake NVML provider (`tests/conftest.py`), so you do
+**not** need an NVIDIA GPU to develop or to run CI. If you do have one, the hardware
+discovery tests are opt-in:
+
+```bash
+GQ_RUN_GPU_TESTS=1 uv run pytest tests/integration
+```
+
+Before opening a pull request:
+
+```bash
+uv run ruff check .
+uv run ruff format .
+uv run mypy
+uv run pytest
+```
+
+### Testing against a scratch instance
+
+Never develop against your real queue. All state is redirectable, so run an isolated
+daemon instead:
+
+```bash
+export GQ_DATA_DIR=/tmp/gq-dev/data
+export GQ_RUNTIME_DIR=/tmp/gq-dev/run
+export GQ_RECONCILE_INTERVAL=0.5
+export GQ_CANCEL_GRACE_SECONDS=2
+gq daemon start
+```
+
+A separate `GQ_RUNTIME_DIR` gets its own lock and socket, so it will not collide with
+a daemon you already have running.
+
+## Scope
+
+The MVP intentionally omits multi-node scheduling, CPU/RAM allocation, preemption,
+MIG, containers, and fractional GPU sharing. Some of these are on the roadmap and
+some are permanent non-goals. Please open an issue to discuss a feature before
+writing it — a rejected PR is a waste of your time, and this project would rather
+stay small than grow every reasonable idea.
+
+## The one rule that matters
+
+> A GPU assigned to a managed job is never simultaneously allocatable.
+
+Everything in `allocator.py`, `scheduler.py`, and `database.py` exists to hold that
+line, and the design **fails closed**: when ownership is ambiguous, the GPU becomes
+`UNKNOWN` and no one gets it. Three consequences to keep in mind when changing
+allocation code:
+
+- **Utilization is never an ownership signal.** A Jupyter kernel sitting at 0% still
+  owns its CUDA context. Only NVML compute-process presence and `gq`'s own durable
+  reservations decide ownership.
+- **The reservation and the state transition are one transaction.** `Database.reserve`
+  moves `WAITING → STARTING` and writes the full GPU assignment inside a single
+  `BEGIN IMMEDIATE`. Do not introduce an `await` or a second allocation between them.
+- **Process identity is checked before signalling.** Use the helpers in
+  `processes.py`; never signal a bare PID. A recycled PID must not be mistaken for
+  the original job.
+
+If a change would weaken any of these, it needs a very good argument and a test that
+demonstrates the new invariant holds.
+
+## Compatibility
+
+- **Database.** Never edit the baseline schema to change an existing table. Append a
+  migration in `MIGRATIONS` in `database.py`, keyed by the version it produces, and
+  bump `SCHEMA_VERSION`. Users have real job history; a release that discards it is a
+  bug. Test your migration against a copy of a populated database.
+- **IPC.** Adding a request type is backward compatible. Changing or removing the
+  meaning of an existing field is not — bump `PROTOCOL_VERSION` in `protocol.py`.
+- **`--json` output** is the supported scripting interface. Adding fields is fine;
+  renaming or removing them requires a protocol bump. Table layouts are for humans
+  and may change freely.
+
+## Style
+
+Match the surrounding code. It is plain, typed Python with no framework: standard
+library plus `nvidia-ml-py`, and `from __future__ import annotations` everywhere.
+
+**Adding a runtime dependency requires a strong justification.** Being installable
+with one small dependency is a feature of this project, not an accident.
+
+Comments explain *why*, especially where the reasoning is subtle — race conditions,
+PID reuse, fail-closed choices. Do not add comments that restate the code.
+
+## Commits and pull requests
+
+Write commit subjects in the imperative mood ("add lease reattachment", not "added"
+or "adds"). Keep the PR description focused on what changed and why; if it fixes an
+issue, link it. A PR that changes behavior should update `CHANGELOG.md` under an
+`## [Unreleased]` heading, and one that changes the interface should update the
+relevant file in `docs/`.
+
+## Reporting bugs
+
+Include your `gq` version (`gq --version`), Linux distribution, Python version, and
+NVIDIA driver version, plus:
+
+```bash
+gq gpu
+gq ps
+gq show JOB            # for a specific job
+tail -n 100 ~/.local/share/gq/gq-daemon.log
+```
+
+Please skim the daemon log before attaching it — it records job commands and file
+paths. **Never attach `gq.sqlite3`**; it contains the stored environment of every
+job. See [SECURITY.md](SECURITY.md).

gq_local-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bo-Jyun Wang
+
+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.

gq_local-0.1.1/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.5
+Name: gq-local
+Version: 0.1.1
+Summary: A small, single-user NVIDIA GPU job scheduler for Linux
+Project-URL: Homepage, https://github.com/BirddWang/gq
+Project-URL: Repository, https://github.com/BirddWang/gq
+Project-URL: Issues, https://github.com/BirddWang/gq/issues
+Project-URL: Changelog, https://github.com/BirddWang/gq/blob/main/CHANGELOG.md
+Author: Bo-Jyun Wang
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: nvidia-ml-py>=12.560.30
+Description-Content-Type: text/markdown
+
+# gq
+
+[![CI](https://github.com/BirddWang/gq/actions/workflows/ci.yml/badge.svg)](https://github.com/BirddWang/gq/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/gq-local)](https://pypi.org/project/gq-local/)
+[![Python](https://img.shields.io/pypi/pyversions/gq-local)](https://pypi.org/project/gq-local/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+A small, single-user GPU job scheduler for one Linux workstation. Queue commands,
+get whole NVIDIA GPUs assigned atomically, and keep jobs running after you close the
+terminal.
+
+```bash
+gq -g 1 uv run train.py          # queued, runs when a GPU is genuinely free
+gq -g 2 torchrun --nproc-per-node=2 train.py
+gq ps                            # what is queued and running
+gq logs -f 12                    # follow a job's output
+```
+
+No cluster, no root, no config file. One `pip install`, one user-level daemon.
+
+## The part that matters
+
+Most of the time, "is this GPU free?" is answered by looking at utilization. That
+answer is wrong in the case that bites hardest on a workstation:
+
+> Your Jupyter kernel finished a cell an hour ago. It sits at **0% utilization** and
+> still holds a CUDA context and several GB of memory. Start a training run on that
+> GPU and you get an OOM — or worse, two jobs quietly fighting over one card.
+
+`gq` treats a GPU as allocatable only when **both** of these hold:
+
+1. `gq` itself has no reservation on it, and
+2. NVML reports no compute process on it that `gq` does not own.
+
+Utilization is never used as an ownership signal. A process `gq` does not recognise
+makes the GPU `EXTERNAL` and off-limits — `gq` routes around it and never kills it.
+When ownership is ambiguous, the GPU becomes `UNKNOWN` and stays unallocated. The
+design fails closed: the worst case is an idle GPU, never a double-booked one.
+
+That care extends to the parts that usually break:
+
+- **Reservation is atomic.** The `WAITING → STARTING` transition and the full GPU
+  assignment are written in one SQLite transaction, before the process launches. A
+  crash between the two is not possible.
+- **Restarts do not lose jobs.** Stopping the daemon leaves your jobs running. On
+  restart it reconciles against saved PID, `/proc` start-time ticks, process group,
+  Linux boot ID, and current GPU UUIDs, and reattaches what it can prove is the same
+  process.
+- **Cancellation cannot hit the wrong process.** `gq` signals a saved process group
+  only after checking process identity, so a recycled PID is never mistaken for your
+  job.
+
+## Install
+
+```bash
+uv tool install gq-local     # or: pipx install gq-local, pip install gq-local
+```
+
+Requires Linux, Python 3.11+, an NVIDIA driver with NVML, and no root. The only
+runtime dependency is `nvidia-ml-py`.
+
+## Quick start
+
+```bash
+gq daemon start          # optional; any command starts it on demand
+gq gpu                   # what each GPU is doing, and who owns it
+gq -g 1 uv run train.py  # submit; returns immediately
+gq ps
+gq logs -f 1
+```
+
+`gq` sets `CUDA_VISIBLE_DEVICES` for the job, so physical GPUs 2,3 appear inside your
+code as `cuda:0` and `cuda:1`.
+
+Scripts can carry their own requirements:
+
+```bash
+#!/bin/bash
+#gq --gpus=2
+#gq --name=experiment
+
+uv run train.py
+```
+
+```bash
+gq submit experiment.sh
+```
+
+Day to day:
+
+| Command | |
+|---|---|
+| `gq -g N CMD...` / `gq run -g N CMD...` | submit a command |
+| `gq submit SCRIPT` | submit a shell script with `#gq` directives |
+| `gq ps [--limit N] [--json]` | list jobs |
+| `gq gpu [--json]` | physical and logical GPU state |
+| `gq show JOB [--json]` | everything about one job |
+| `gq logs [-f] JOB` | read or follow a job's output |
+| `gq cancel JOB` | `SIGTERM` the process group, then `SIGKILL` after a grace period |
+| `gq rm JOB...` | delete terminal jobs and their logs |
+| `gq clean --older-than 30d` | sweep old terminal jobs and their logs |
+| `gq daemon start\|stop\|status` | manage the daemon |
+
+`--json` is the supported scripting interface; table layouts may change between
+releases.
+
+## A note on secrets
+
+A queued job may not start for hours, so `gq` saves your environment in order to run
+it later with the same context. Variables that look like credentials are dropped
+rather than stored, and `gq` tells you which:
+
+```text
+gq: not persisting 1 secret-looking variable(s): HF_TOKEN
+    use --env-all (or GQ_ENV_ALL=1) to keep them, or --env-keep NAME
+```
+
+If a job genuinely needs one, `--env-keep HF_TOKEN` puts it back. Anything kept is
+stored in plaintext in a `0600` SQLite database — see [SECURITY.md](SECURITY.md).
+
+## Is this the right tool?
+
+| You want | Use |
+|---|---|
+| Many machines, many users, fair-share, accounting | Slurm, or a Kubernetes scheduler |
+| One workstation, your own jobs, whole GPUs, zero setup | **gq** |
+| A generic job queue with no GPU awareness | [task-spooler](https://vicerveza.homeunix.net/~viric/soft/ts/) |
+| Cloud or multi-node orchestration for ML | SkyPilot, Determined |
+
+`gq` deliberately does **not** do multi-node scheduling, multiple users, CPU/RAM
+allocation, priorities, preemption, MIG, containers, or fractional GPU sharing. Some
+of those are on the roadmap; see [CONTRIBUTING.md](CONTRIBUTING.md#scope) before
+proposing one.
+
+## Documentation
+
+- [Usage](docs/usage.md) — every command, `#gq` directives, environment handling, retention
+- [Architecture](docs/architecture.md) — allocation invariant, IPC, crash and reboot recovery
+- [Troubleshooting](docs/troubleshooting.md) — stuck GPUs, stuck jobs, daemon problems
+- [Security](SECURITY.md) — threat model and how credentials are handled
+- [Changelog](CHANGELOG.md)
+
+## Development
+
+```bash
+git clone https://github.com/BirddWang/gq
+cd gq
+uv sync --all-groups
+uv run pytest
+```
+
+The suite runs against a fake NVML provider, so **no GPU is required** to develop or
+to run CI. Hardware tests are opt-in:
+
+```bash
+GQ_RUN_GPU_TESTS=1 uv run pytest tests/integration
+```
+
+Contributions are welcome — please read [CONTRIBUTING.md](CONTRIBUTING.md) first,
+especially the section on the allocation invariant.
+
+## License
+
+MIT — see [LICENSE](LICENSE).