slurmate 0.5.1

███████╗██╗     ██╗   ██╗██████╗ ███╗   ███╗ █████╗ ████████╗███████╗
██╔════╝██║     ██║   ██║██╔══██╗████╗ ████║██╔══██╗╚══██╔══╝██╔════╝
███████╗██║     ██║   ██║██████╔╝██╔████╔██║███████║   ██║   █████╗  
╚════██║██║     ██║   ██║██╔══██╗██║╚██╔╝██║██╔══██║   ██║   ██╔══╝  
███████║███████╗╚██████╔╝██║  ██║██║ ╚═╝ ██║██║  ██║   ██║   ███████╗
╚══════╝╚══════╝ ╚═════╝ ╚═╝  ╚═╝╚═╝     ╚═╝╚═╝  ╚═╝   ╚═╝   ╚══════╝

✨ Why Slurmate?

Writing #SBATCH headers by hand is fiddly and error-prone: which partition has H100s? what's the memory limit? did I get the --gres syntax right for this cluster? Slurmate turns that into a guided conversation — it reads your cluster live, validates as you go, and hands you a clean, ready-to-submit script.

slurmate

That's it. Answer a few prompts, watch the script build itself in a live preview, and submit — or save it for later.

🚀 Quick start

# Recommended: isolated install
pipx install slurmate

# or plain pip
pip install slurmate

git clone https://github.com/PursuitOfDataScience/slurmate.git
cd slurmate
pip install -e ".[dev]"     # editable + dev tools (pytest, ruff, mypy)

Interactive mode (the TUI)

slurmate

A full-screen wizard walks you through name → resources → environment → command. The generated script grows live in a preview pane as you answer. A final Review & Submit screen shows your full configuration and the generated script side by side, then a single menu lets you submit, go back to edit your answers, open the script in $EDITOR, save it, or quit.

💡 You can leave any step blank and come back to it — anything still missing is flagged before you submit. Esc / Shift+Tab go back at any step (including from the action menu, to re-edit your answers); navigation is fully keyboard-driven.

Batch mode (scriptable, no TUI)

slurmate \
  --job-name train_job \
  --partition gpu \
  --cpus 8 --memory 32G --time 04:00:00 \
  --gpus 1 --gpu-type h100 \
  --command "python train.py"

Submit immediately, no prompts:

slurmate --partition gpu --command "python train.py" --yes

Just want the script? --print emits only the raw script (great for piping or CI):

slurmate --partition gpu --command "python train.py" --print > job.sbatch

Want a full preview without submitting? --dry-run shows the summary panel, partition-limit warnings, SU/ETA, and any missing-field reminders — everything except the actual submit:

slurmate --partition gpu --command "python train.py" --dry-run

Batch mode kicks in as soon as you pass any job-defining flag (or --yes); a bare slurmate still launches the wizard. If a config file supplies the job, --print and --dry-run also render non-interactively from it — so slurmate --print with a .slurmate.toml present emits the script straight to stdout without opening the wizard. --yes requires a command to run (it refuses to submit an empty, no-op job). Every submit also saves a <job>-<id>.sh copy next to where you ran it — pass --no-save-script (or set SLURMATE_NO_SAVE=1) to skip that.

Run slurmate --help for the full flag list.

🎯 Features

⚙️ Configuration file

Stop retyping the same account and partition every run. Slurmate reads defaults from a TOML file (first match wins):

1. .slurmate.toml in the current directory
2. ~/.config/slurmate/config.toml

These prefill the wizard and act as fallbacks in batch mode. Explicit CLI flags always win.

# .slurmate.toml — keys may be top-level or under a [defaults]/[slurmate] table
account     = "my_lab"
partition   = "gpu-shared"
cpus        = 8
memory      = "32G"
time_limit  = "04:00:00"
gpu_format  = "gres_type"            # gres_type | constraint | gpus
env_type    = "conda"                # conda | mamba | venv | none
modules     = ["cuda/12.1", "gcc/9.3.0"]
output_dir  = "logs"

Recognized keys: job_name, account, partition, qos, cpus, memory, time_limit, nodes, ntasks_per_node, gpus, gpu_type, gpu_format, array_spec, modules, env_type, env_name, output_dir, output_file, command, custom_sbatch.

Keys may sit at the top level or under a [defaults] or [slurmate] table. When the same key appears in more than one place, the effective precedence is [slurmate] > [defaults] > top-level (a later table wins). Explicit CLI flags always override the file.

Real TOML is always used on supported Pythons (tomllib on 3.11+, the tomli dependency on 3.10). A minimal flat key = value reader exists only as a last-resort fallback.

🔧 Environment variables

NO_COLOR and non-TTY output are respected automatically.

🛠️ How it works

1. Gather — query the cluster (or fall back to mock data) for partitions, limits, GPU types, environments, and modules.
2. Guide — a keyboard-first wizard collects name, resources, dependencies, and the command, validating against the chosen partition as you go.
3. Generate & submit — produce a clean #SBATCH script, optionally edit it in $EDITOR, then pipe it straight to sbatch (or save / print it).

🧪 Status

Slurmate is beta and pre-1.0 — the CLI, config keys, and defaults may change between releases. It's already useful day-to-day; pin a version if you script around it. Bug reports and cluster-specific quirks are very welcome.

🤝 Contributing

Issues and PRs are welcome! For local development:

pip install -e ".[dev]"
ruff check src/        # lint
mypy src/              # types (strict)
pytest                 # tests

CI runs the same three checks on Python 3.10–3.13 for every push and PR.

📄 License

Released under the MIT License.