Metadata-Version: 2.4
Name: molcrafts-molq
Version: 0.2.0
Summary: Unified job queue for local execution and HPC schedulers
Author-email: Roy Kid <lijichen365@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/MolCrafts/molq
Project-URL: Documentation, https://github.com/MolCrafts/molq/tree/master/docs
Project-URL: Repository, https://github.com/MolCrafts/molq
Project-URL: Issues, https://github.com/MolCrafts/molq/issues
Project-URL: Changelog, https://github.com/MolCrafts/molq/blob/master/CHANGELOG.md
Keywords: job,queue,cluster,slurm,hpc,scheduler
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9
Requires-Dist: rich>=14.3.3
Requires-Dist: molcrafts-mollog
Requires-Dist: molcrafts-molcfg
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: coverage[toml]; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: ty; extra == "dev"
Provides-Extra: docs
Requires-Dist: zensical>=0.0.27; extra == "docs"
Dynamic: license-file

# molq

[![CI](https://github.com/MolCrafts/molq/actions/workflows/ci.yml/badge.svg)](https://github.com/MolCrafts/molq/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/molcrafts-molq.svg)](https://pypi.org/project/molcrafts-molq/)
[![Python](https://img.shields.io/badge/python-3.12%2B-3776AB.svg?logo=python&logoColor=white)](./pyproject.toml)
[![License](https://img.shields.io/badge/license-MIT-16A34A.svg)](./LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)

Unified job queue for Python workloads that need the same submission API on a laptop, workstation, or HPC cluster.

## Quick Start

```bash
pip install molcrafts-molq
```

```python
from molq import Duration, JobResources, Memory, Submitor

local = Submitor("devbox", "local")

job = local.submit(
    argv=["python", "train.py"],
    resources=JobResources(
        cpu_count=4,
        memory=Memory.gb(8),
        time_limit=Duration.hours(2),
    ),
)

record = job.wait()
assert record.state.value == "succeeded"
```

## Features

- One `Submitor` API for `local`, `slurm`, `pbs`, and `lsf`
- Typed submission inputs with `Memory`, `Duration`, `Script`, `JobResources`, `JobScheduling`, and `JobExecution`
- SQLite-backed persistence with WAL mode and UUID job identities
- Reconciliation and blocking waits through `JobReconciler` and `JobMonitor`
- First-class retry lineage with persisted attempt history
- Molq job-id dependencies and inspectable dependency metadata
- Profiles from `~/.molq/config.toml` plus reusable defaults
- Cleanup and lightweight daemon workflows for retention and reconciliation
- Event hooks through `EventBus`
- Rich CLI for `submit`, `list`, `status`, `watch`, `logs`, `history`, `inspect`, `cleanup`, `daemon`, `monitor`, and `cancel`
- Default stdout/stderr capture for every submitted job

## Retry and Dependency Example

```python
from molq import RetryBackoff, RetryPolicy, Submitor

slurm = Submitor("hpc", "slurm")

train = slurm.submit(
    argv=["python", "train.py"],
    retry=RetryPolicy(
        max_attempts=3,
        backoff=RetryBackoff(initial_seconds=10, maximum_seconds=60),
    ),
)

eval_job = slurm.submit(
    argv=["python", "eval.py"],
    after_success=[train.job_id],
)
```

## Profile Example

`~/.molq/config.toml`

```toml
[profiles.gpu]
scheduler = "slurm"
cluster_name = "hpc"

[profiles.gpu.defaults.resources]
cpu_count = 8
memory = "34359738368"

[profiles.gpu.defaults.scheduling]
queue = "gpu"

[profiles.gpu.retry]
max_attempts = 3
```

CLI usage:

```bash
molq submit slurm --profile gpu python train.py
molq daemon slurm --profile gpu --once
molq cleanup slurm --profile gpu --dry-run
```

## Documentation

- [Getting Started](docs/getting-started.md) for installation and first-job examples
- [Scheduler Guide](docs/schedulers.md) for backend capabilities and scheduler options
- [Monitoring Guide](docs/monitoring.md) for lifecycle, polling, and dashboards
- [API Reference](docs/api.md) for the exported classes and functions
- [CLI Reference](docs/cli.md) for command-line usage

---

Built by [MolCrafts](https://github.com/MolCrafts) with love.
