✨qqtools✨

PyPI - Monthly Downloads Python version

A lightweight library, crafted and battle-tested daily by qq, to make PyTorch life a little easier.

It started from the frustration of PyG’s tightly coupled CUDA ecosystem—carefully matching CUDA versions, installing wheel builds from the official index, and repeatedly reinstalling dependencies like torch-scatter whenever anything changed. This project brings back a clean, one-line pip install ... experience, with no need to worry about CUDA compatibility.

I’ve gathered the repetitive parts of my day-to-day work and refined them into this slim utility library. It serves as a unified toolkit for handling data, training, and experiments, designed to keep projects moving fast with cleaner code and smoother workflows.

Built for me, shared for you.

What it includes

At its core, qqtools is a collection of small utilities I use around PyTorch projects:

data containers such as qDict and qData
dataset and dataloader helpers such as qDictDataset and qDictDataloader
small neural network helpers such as qMLP
a lightweight training framework, qpipeline
a command-line experiment queue for Linux, qexp
config and serialization helpers for YAML, JSON, pickle, and LMDB

At the core, it is still a practical toolbox for the repetitive parts around experiments.

Install

# Core install
pip install qqtools

# Full install
pip install qqtools[full]

# If you only want the experiment queue extras:
pip install qqtools[exp]

While some parts still work with torch==1.x, torch>=2.4 is recommended

qDict

qDict is mainly there for cleaner attribute access in batch-like code:

# Instead of dirty dict brackets:
# batch["input_ids"], batch["attention_mask"]

# Use clean attribute access:
batch = qt.qDict({"input_ids": input_ids, "attention_mask": attention_mask})
out = model(batch.input_ids)

Context scope and `qt.use_ctx`

qt.ctx provides a lightweight scoped context. Values set inside with qt.ctx(...) are visible only in that scope and its nested calls, and the outer state is restored automatically when the block exits.

Scope exit restores the previous key bindings. If you intentionally mutate a shared mutable object in place through the live context, that mutation is considered caller-managed behavior and may remain visible outside the block.

import qqtools as qt

with qt.ctx(dim=512):
    print(qt.ctx.dim)  # 512

print(qt.ctx.get("dim"))  # None

@qt.use_ctx is the simplest way to inject context values into a class constructor:

import qqtools as qt


@qt.use_ctx
class AttentionLayer:
    def __init__(self, dim=64, heads=8):
        self.dim = dim
        self.heads = heads


with qt.ctx(dim=512, heads=16):
    layer = AttentionLayer()
    print(layer.dim, layer.heads)  # 512 16

Manual constructor arguments still take precedence over injected context values.

qexp

qexp is a lightweight experiment queue for Linux hosts. It is built around a shared project root, can work on multi-machines with multi-GPUs.

Quick start:

qexp init --shared-root /mnt/share/myproject/.qexp --machine gpu-a
qexp submit --name demo1 -- python train.py -c config1.yaml
qexp submit --name demo2 -- python train.py -c config2.yaml
qexp submit --name demo3 -- python train.py -c config3.yaml
# 3 tasks will be queued and run sequentially

After init, qexp saves the current shared_root and machine as CLI context, so you usually do not need to repeat them on every command.

Agent lifecycle is configured separately from how it is launched. on_demand (the default) automatically starts for local submissions and exits after true idleness. daemon stays active until stopped. qexp agent start always launches in the background, while qexp agent run is the foreground debugging command.

qexp init --shared-root /mnt/share/myproject/.qexp --machine gpu-a --agent-mode daemon
qexp agent start
qexp agent status
qexp agent stop

Schema 6 operation

qexp schema 6 uses the Group, Task, and Attempt runtime. Batch-era roots are not compatible. A drained schema-5 root can be upgraded only when it has no active claim or running Attempt:

qexp migrate --shared-root /path/to/project/.qexp --machine gpu1 --to-schema 6

The agent owns lease renewal, Recovery, termination, terminal publication, and GPU reservation release. The runner only starts the training process and writes local process registration and exit-observation records. Inspect or change the shared lease policy only while no active claim exists:

qexp lease-policy show
qexp lease-policy set --ttl-seconds 180 --renew-interval-seconds 10
qexp doctor verify

Schema 6 detects clock capability instead of requiring chronyc on every host. A qualified provider permits full bounded-lease coordination; otherwise eligible work runs in holder-bound local-safe mode and is never expired, remotely recovered, or automatically replaced. qexp doctor verify and qexp agent status expose the provider, authority mode, and blocker.

qexp task share TASK_ID
qexp task share TASK_ID --after 10m --with gpu-b --with gpu-c
qexp task keep-local TASK_ID
qexp task offer TASK_ID --format json

share is the user-facing control for letting eligible Group workers help while the home machine remains eligible. share --after records a bounded deadline; keep-local clears the shared policy and returns the Task to the home queue. task offer is retained for Tasks that were already submitted with spillover policy and only moves that existing policy into the shared queue.

For normal task and cleanup workflows:

qexp submit --group sweep -- python train.py --config a.yaml
qexp batch-submit --group sweep --file runs.yaml
qexp group pause sweep
qexp task retry TASK_ID
qexp task retry TASK_ID --acknowledge-duplicate-risk
qexp clean --task-id TASK_ID --dry-run
qexp clean --older-than-days 30 --limit 100

batch-submit manifests may set Group workers and nested placement defaults, with per-Task overrides:

group:
  workers: [g1, g2]
defaults:
  placement:
    home_machine: current
    sharing:
      mode: spillover
      fallback_machines: group
tasks:
  - command: [python, train.py]
  - placement:
      sharing:
        mode: private
    command: [python, control.py]

During a shared-filesystem outage, the owning agent retains the training process and GPU reservation in suspect and then isolated state; it does not create a replacement Attempt or impose an automatic kill deadline. When shared authority becomes available again, the agent renews the same claim, recovers the same orphaned Attempt with a new token, or terminates the old process through its durable termination-decision path if authority changed.

Cleanup waits for required machines to acknowledge removal of matching local GPU reservations, process manifests, and logs before deleting shared Task and Attempt records. Required machines are the Task home machine, historical Attempt machines, and the machine that prepared cleanup. Pending operations report waiting_ack and the remaining machine names. Cleanup blocks retry, claim, cancel, and offer, and its tombstone permanently reserves the Task ID.

batch-submit is only a bulk-input command and does not create a public Batch identity.

Python API:

from qqtools.plugins import qexp

task = qexp.submit(
    qexp.load_root_config("/mnt/share/myproject/.qexp", "gpu-a"),
    command=["python", "train.py", "--epochs", "10"],
    name="demo",
)
print(task.task_id)

Note: Run pip install qqtools[exp] before use qexp command.

qpipeline

qpipeline is a minimal training loop scaffold. It doesn't try to be a heavy framework. You write the project-specific model and task logic, and qpipeline handles the repetitive boilerplate: config-driven startup, train/val loops, metric aggregation, and checkpointing.

A tight training entry:

import torch
from qqtools.plugins.qpipeline import prepare_cmd_args, qPipeline
from qqtools.nn import qMLP

class MyTask:
    def __init__(self, args):
        # Your custom data logic goes here
        self.train_loader, self.val_loader = build_loaders(args)

    def batch_forward(self, model, batch):
        return {"pred": model(batch.x)}

    def batch_loss(self, out, batch):
        loss = torch.nn.functional.mse_loss(out["pred"], batch.y)
        return {"loss": (loss, len(batch.y))}

    def batch_metric(self, out, batch):
        mae = (out["pred"] - batch.y).abs().mean()
        return {"mae": (mae, len(batch.y))}

    def post_metric_to_err(self, result):
        return result["mae"]

class MyPipeline(qPipeline):
    @staticmethod
    def prepare_model(args):
        return qMLP([16, 8, 1])

    @staticmethod
    def prepare_task(args):
        return MyTask(args)

if __name__ == "__main__":
    args = prepare_cmd_args()
    pipe = MyPipeline(args, train=True)
    pipe.fit()

Because qpipeline enforces a stable entry contract, it pairs perfectly with qexp for queued execution:

qexp submit -- python entry.py --config configs/train.yaml

For one-off runtime config edits, qpipeline also supports dotted CLI overrides after normal parser handling:

python entry.py \
  --config configs/train.yaml \
  --task.dataloader.eval_batch_size 32 \
  --task.val_split val_ood \
  --runner.fast_dev_run

Configuration follows a standard YAML structure. See qConfig.md for details.

Plugin modules

Under src/qqtools/plugins/, there are also:

qchem - tools for reading and processing quantum chemistry outputs
qpipeline - a training pipeline framework built on top of the core torch utilities
qhyperconnect - an implementation of Hyper-Connection for PyTorch

Test

tox

Release files for qqtools 1.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for qqtools 1.3.1
File	Size	Uploaded
qqtools-1.3.1.tar.gz	245.3 kB	Aug 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for qqtools 1.3.1
File	Interpreter	ABI	Platform	Reset
qqtools-1.3.1-py3-none-any.whl 302.9 kB Aug 7, 2026	Python 3	none	any	Details

Total release size: 548.2 kB

Release files / qqtools-1.3.1.tar.gz

Download URL	qqtools-1.3.1.tar.gz
Size	245.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`24d6070c759c761b8951adfcf1dba313ff3bf9dd0e4afaf4eb94020ed9a04c89`
BLAKE2b-256 checksum How to use checksums	`b045938bc0feb02900db537da8fd39323d3de4496e6690c8b50902aec6e0cc2d`
Upload date	Aug 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / qqtools-1.3.1-py3-none-any.whl

Download URL	qqtools-1.3.1-py3-none-any.whl
Size	302.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`eb58e0e98d864a606917acc7ceb80167f06bb0bc416a5c1a85778d2391e2ea03`
BLAKE2b-256 checksum How to use checksums	`a580721a137462eae637a297946b311e46af26771eac6c5fc265c1f2a8ca5736`
Upload date	Aug 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`