molq

Unified job queue — one submission API for local, SLURM, PBS, and LSF

Documentation · Quick start · Ecosystem

molq is a unified job queue for Python workloads that need the same submission API on a laptop, a workstation, or an HPC cluster. A Cluster says where jobs run, a Submitor tracks how they progress — and the same code runs against local subprocesses or remote schedulers over SSH.

Under active development. Public APIs may change between minor releases.

Capabilities

Module	Capability
`cluster`	`Cluster` — destination spec: scheduler kind × transport × scheduler options, plus live queue snapshots
`submitor`	`Submitor` + `JobHandle` — single entry point for submitting, tracking, and waiting on jobs
`scheduler`	`Scheduler` protocol plus one module per backend (`shell`, `slurm`, `pbs`, `lsf`), each routing shell calls through a transport and owning its own directive and dependency syntax
`transport`	`LocalTransport` / `SshTransport` — runs shell and file ops here or on a remote host via OpenSSH, sharing one multiplexed connection
`store`	`JobStore` — SQLite persistence with WAL mode, UUID job identity, schema versioning, and v1 auto-migration
`validation`	Checks a request against the backend's declared capability matrix before submitting
`jobpaths`	Job directory layout, log path resolution, script staging, and manifests
`dependencies`	Resolves molq job ids + conditions into the backend's submit syntax
`retry` / `retention`	Retry eligibility and backoff; expiry of job directories and old records
`artifacts`	Pulls logs and job directories back from the cluster
`reconciler`	`JobReconciler` — batch-queries schedulers, diffs against the store, syncs job state
`monitor`	Blocking waits and polling engine driven by pluggable strategies
`strategies`	Pluggable polling strategies; exponential backoff by default
`callbacks`	`EventBus` — synchronous pub/sub for job lifecycle events with handler isolation
`models`	Job data models — `JobRecord`, `RetryPolicy`, `RetentionPolicy`, `JobDependency`, `SubmitorDefaults`
`types`	Frozen value types — `Memory`, `Duration`, `Script`, `JobResources`, `JobScheduling`, `JobExecution`
`options`	Per-scheduler frozen option dataclasses (`Local`, `Slurm`, `PBS`, `LSF`) — no untyped dicts
`config`	Profile and config loading from molcfg (`~/.molcrafts/molq/config/config.toml`, or `MOLCRAFTS_HOME`)
`plugin`	`MolqPlugin` host — official builtins + third-party entry points (`molq.plugins`)
`plugins`	Official plugins (e.g. `nerve` → local Nerve menu-bar status; fail-open)
`workspace`	`Workspace` / `Project` — directory handles over a cluster's filesystem (local or remote)
`ssh_config`	Surfaces `~/.ssh/config` hosts as cluster candidates
`serde`	Serialization helpers for stored requests and config-driven values
`errors`	Unified `MolqError` exception hierarchy with typed context
`status`	`JobState` enum with terminal-state semantics
`merge`	Pure function that merges per-submit parameters with `Submitor` defaults
`dashboard`	Full-screen terminal dashboard for monitoring runs and jobs
`testing`	`FakeScheduler` and `make_submitor` for tests and runnable examples without a real cluster
`cli`	Typer + Rich CLI: jobs (`submit`/`list`/`status`/`logs`/`cancel`/…), live (`watch`/`monitor`/`daemon`), setup (`clusters`/`workspace`/`plugins`)

Install

pip install molcrafts-molq

Requires Python 3.12+. Depends on typer, rich, molcrafts-mollog, and molcrafts-molcfg.

Quick start

import molq as mq

# Cluster = destination (where to run). Submitor = lifecycle (how jobs are tracked).
cluster = mq.Cluster("devbox", "local")

with mq.Submitor(target=cluster) as queue:
    handle = queue.submit_job(
        argv=["python", "-c", "print('hello from molq')"]
    )
    record = handle.wait()

print(record.state)

Swap to a cluster by changing one line — mq.Cluster("hpc", "slurm", host="user@hpc.example.com") — and the rest of the code is unchanged. See the documentation for retries, dependencies, profiles, and the CLI.

Documentation

Quickstart — install and complete a local job
Mental model — understand destinations, tracking, and records
Submit jobs — commands, resources, retries, and dependencies
Clusters and schedulers — local, SSH, SLURM, PBS, and LSF
Monitor jobs — status, logs, history, and dashboards
Remote files — stage inputs and collect results
Command line — task-oriented CLI workflows
Plugins and Nerve — lifecycle observers and menu-bar status
Configuration — profiles, defaults, and remote destinations
Python API — generated, responsibility-based reference

MolCrafts ecosystem

Project	Role
molpy	Python toolkit — the shared molecular data model & workflow layer
molrs	Rust core — molecular data structures & compute kernels (native + WASM)
molpack	Packmol-grade molecular packing (Rust + Python)
molvis	WebGL molecular visualization & editing
molexp	Workflow & experiment-management platform
molnex	Molecular machine-learning framework
molq	Unified job queue — local / SLURM / PBS / LSF — this repo
molcfg	Layered configuration library
mollog	Structured logging, stdlib-compatible
molhub	Molecular dataset hub
molmcp	MCP server for the ecosystem
molrec	Atomistic record specification

Contributing

Issues and pull requests are welcome — see CONTRIBUTING.md for development setup.

License

MIT — see LICENSE.

_{Crafted with 💚 by MolCrafts}

Metadata

Release files for molcrafts-molq 0.8.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 molcrafts-molq 0.8.1
File	Size	Uploaded	Provenance
molcrafts_molq-0.8.1.tar.gz	176.7 kB	Aug 13, 2026	With provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for molcrafts-molq 0.8.1
File	Interpreter	ABI	Platform	Reset
molcrafts_molq-0.8.1-py3-none-any.whl 127.5 kB Aug 13, 2026 With provenance	Python 3	none	any	Details

Total release size: 304.2 kB

Release files / molcrafts_molq-0.8.1.tar.gz

Download URL	molcrafts_molq-0.8.1.tar.gz
Size	176.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`41e42d12c94823ca68aab4b6037888c66dc93d2048433eb02c836c212f47ad28`
BLAKE2b-256 checksum How to use checksums	`2a1f708a1fd2785496b26f5abb8d8aaf40c6b42f8aea83c247b0f324f17fd435`
Upload date	Aug 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/MolCrafts/molq
Publishing commit: github.com/MolCrafts/molq/tree/2c9954ede2654cfa200de56de4e96bae430985ab

Workflow

Publishing configuration: github.com/MolCrafts/molq/blob/2c9954ede2654cfa200de56de4e96bae430985ab/.github/workflows/release.yml
Publishing logs: github.com/MolCrafts/molq/actions/runs/31685639136/attempts/1

Artifact

Subject: molcrafts_molq-0.8.1.tar.gz
SHA-256 checksum: 41e42d12c94823ca68aab4b6037888c66dc93d2048433eb02c836c212f47ad28 Verifying attestations

Release files / molcrafts_molq-0.8.1-py3-none-any.whl

Download URL	molcrafts_molq-0.8.1-py3-none-any.whl
Size	127.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d019d972f24168b1980da3dca65d6403bfc4daf7a6209d5bb28f4afd00d8b218`
BLAKE2b-256 checksum How to use checksums	`a57585f02fff6f82a4d1d32e05fcfc428d201f29dd446ecf14f655b763119a5d`
Upload date	Aug 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/MolCrafts/molq
Publishing commit: github.com/MolCrafts/molq/tree/2c9954ede2654cfa200de56de4e96bae430985ab

Workflow

Publishing configuration: github.com/MolCrafts/molq/blob/2c9954ede2654cfa200de56de4e96bae430985ab/.github/workflows/release.yml
Publishing logs: github.com/MolCrafts/molq/actions/runs/31685639136/attempts/1

Artifact

Subject: molcrafts_molq-0.8.1-py3-none-any.whl
SHA-256 checksum: d019d972f24168b1980da3dca65d6403bfc4daf7a6209d5bb28f4afd00d8b218 Verifying attestations

Security for molcrafts-molq 0.8.1

Report project as malware

Provenance

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Attestation for molcrafts_molq-0.8.1.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/MolCrafts/molq
Publishing commit: github.com/MolCrafts/molq/tree/2c9954ede2654cfa200de56de4e96bae430985ab

Workflow

Publishing configuration: github.com/MolCrafts/molq/blob/2c9954ede2654cfa200de56de4e96bae430985ab/.github/workflows/release.yml
Publishing logs: github.com/MolCrafts/molq/actions/runs/31685639136/attempts/1

Artifact

Subject: molcrafts_molq-0.8.1.tar.gz
SHA-256 checksum: 41e42d12c94823ca68aab4b6037888c66dc93d2048433eb02c836c212f47ad28 Verifying attestations

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.