pysalvo 0.2.0__tar.gz

pysalvo-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --all-extras
+      - run: uv run pre-commit run --all-files
+      - run: uv run mypy src/salvo
+      - run: uv run pytest -v
+      - run: uv build
+      - name: Smoke-import built wheel
+        run: |
+          python -m venv /tmp/wheel-smoke
+          /tmp/wheel-smoke/bin/pip install --quiet dist/pysalvo-*.whl
+          /tmp/wheel-smoke/bin/python -c "from salvo import JobSpec, render; from salvo.policy import apply_oom, OomContext; from salvo.topology import load_preset"

pysalvo-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: release
+on:
+  push:
+    tags: ["v*"]
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Verify tag matches pyproject version
+        env:
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          tag="${REF_NAME#v}"
+          ver=$(uv run python -c "import tomllib,pathlib;print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          [ "$tag" = "$ver" ] || { echo "tag=$tag pyproject=$ver"; exit 1; }
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pysalvo
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

pysalvo-0.2.0/.gitignore

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

pysalvo-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.5.5
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [pydantic>=2.6, types-pyyaml]
+        files: ^src/salvo

pysalvo-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+## Adding a cluster
+
+The fastest contribution is a new cluster preset. Each preset is a single YAML file under `src/salvo/topology/presets/`. The schema lives in `src/salvo/topology/schema.py` (pydantic v2, frozen, `extra="forbid"`).
+
+1. Copy an existing preset closest to your cluster (DRAC: `rorqual.yaml`; campus: `mila.yaml`).
+2. Edit accounts, partitions, GPU types, walltime caps, defaults.
+3. Add an entry to `src/salvo/topology/detect.py` for the hostname pattern.
+4. Open a PR with the YAML + a one-line entry in the README cluster table.
+
+Tests will exercise your preset via the parametrized suite in `tests/unit/test_presets.py`.
+
+## Dev setup
+
+    git clone <repo>
+    cd salvo
+    uv sync --all-extras
+    uv run pre-commit install
+    uv run pytest
+
+## Style
+
+- Python 3.11+, ruff + mypy strict, line length 100.
+- Pydantic v2 models are frozen and `extra="forbid"`.
+- Public functions get type hints; tests get docstrings on intent (not behaviour).
+- No mutable defaults, no f-strings in log messages.
+
+## Test layers
+
+- **Layer A** (`tests/unit/`): pure-Python, no subprocess.
+- **Layer B** (`tests/integration/`): subprocess to fake `sbatch` via `tests/conftest.py:fake_sbatch`. Golden sbatch files in `tests/integration/golden/`.
+- **Layer C** (cluster nightly): not run on PRs.
+- **Perf** (`tests/perf/`): budget smoke tests.
+
+PRs must keep total coverage at or above 80% and add tests for every new dispatch rule.
+
+## Commit style
+
+Conventional commits with module-scoped scope: `feat(job):`, `fix(dispatch):`, `test(integration):`, `docs:`, `chore:`.

pysalvo-0.2.0/LICENSE

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

pysalvo-0.2.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: pysalvo
+Version: 0.2.0
+Summary: Render + policy library for SLURM JobSpecs (Mila + DRAC clusters)
+Project-URL: Homepage, https://github.com/wietzesuijker/salvo
+Project-URL: Source, https://github.com/wietzesuijker/salvo
+Project-URL: Issues, https://github.com/wietzesuijker/salvo/issues
+Author: W
+License: MIT
+License-File: LICENSE
+Keywords: alliance-canada,drac,hpc,mila,sbatch,slurm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Clustering
+Classifier: Topic :: System :: Distributed Computing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: typer>=0.12
+Provides-Extra: all
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pre-commit>=3.7; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: drac
+Provides-Extra: mila
+Description-Content-Type: text/markdown
+
+# salvo
+
+Policy and render library for SLURM. salvo turns a `JobSpec` into byte-stable sbatch text and decides what to do when a job hits OOM or gets preempted. It does not move code to the cluster, does not open SSH connections, and is not a runner. For transport, pair it with [cluv](https://github.com/mila-iqia/cluv) or invoke `sbatch` directly.
+
+## Install
+
+    pip install pysalvo
+
+Two CLI commands ship for diagnostics and one-shot rendering. Everything else is meant to be imported.
+
+    salvo doctor                                 # topology, ssh alias hygiene, manifest freshness
+    salvo render spec.yaml --cluster mila        # JobSpec YAML to sbatch text on stdout
+
+## Render
+
+```python
+from salvo import JobSpec, render
+
+spec = JobSpec(
+    name="train",
+    cmd=["python", "train.py"],
+    gpus=1, cpus=8, mem="32G", time="2h",
+    on_oom=["bump_mem(1.5x, max=128G)", "fail"],
+)
+
+sbatch_text = render(
+    spec,
+    cluster_id="mila",
+    account="mila",
+    partition="unkillable",
+)  # str, byte-stable, no side effects
+```
+
+Same JobSpec, same cluster, same inputs, same bytes every run. Useful when you need to audit what was actually submitted six months later.
+
+If you leave `account` and `partition` off, salvo picks them via `salvo.dispatch` by shelling out to `squeue` for live capacity. That path only works on a SLURM login node; library callers (cluv, xgenius) should pass both explicitly to keep `render()` pure.
+
+## OOM policy
+
+```python
+from salvo.policy import parse, apply_oom, OomContext
+
+steps = parse(["bump_mem(1.5x, max=128G)", "escalate_partition", "fail"])
+
+new_spec, action = apply_oom(prev_spec, OomContext(kind="cpu", max_rss_mb=33_500))
+# new_spec is a fresh JobSpec with bumped mem, or None if the policy says fail
+```
+
+The DSL is intentionally small. Steps run in order until one applies:
+
+- `bump_mem(<factor>x, max=<size>)` — multiplicative bump, capped
+- `escalate_partition` — clear partition so the next render picks a larger tier
+- `fail` — terminal
+- `bump_gpus(...)`, `callback(...)` — parse today, execute in a later release
+
+## Cluster topology
+
+Five presets ship in `salvo/topology/presets/`: `mila`, `rorqual`, `narval`, `beluga`, `cedar`. More DRAC clusters land as YAMLs are contributed. Each YAML lists accounts, partitions, and capacity rules.
+
+```python
+from salvo.topology import load_preset, list_presets
+
+list_presets()                      # ['beluga', 'cedar', 'mila', 'narval', 'rorqual']
+cluster = load_preset("mila")       # ClusterTopology
+```
+
+Contributing a new cluster is one YAML file. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Decorator (optional, Python-native)
+
+If you'd rather write a function than a YAML spec:
+
+```python
+from salvo import cluster
+
+@cluster.submit(gpus=1, cpus=8, mem="32G", time="2h",
+                on_oom=["bump_mem(1.5x, max=128G)", "fail"])
+def train(seed: int):
+    ...
+
+handle = train.submit(seed=42)
+```
+
+`train.submit(...)` runs the local-sbatch convenience path: it renders, calls `sbatch`, and returns a handle. Skip the decorator if you're embedding salvo inside another tool's submit flow; just call `render()` and let that tool do the submission.
+
+## Use with cluv
+
+cluv handles SSH, code sync, and the `sbatch` call. salvo handles the policy. The natural composition is cluv importing salvo's policy library when a user opts in:
+
+```toml
+# in your project's pyproject.toml
+[tool.cluv.retry]
+on_oom = ["bump_mem(1.5x, max=128G)", "fail"]
+max_hops = 5
+```
+
+This is a proposal, not a shipped feature in cluv. An upstream issue is in draft.
+
+## Use with anything that calls sbatch
+
+salvo has no SSH or async dependencies. It is a pydantic + stdlib library. Any tool that runs `sbatch` can import `salvo.render`, `salvo.policy.apply_oom`, and `salvo.topology.load_preset` independently. Two runnable examples under [`examples/`](examples/) show the wiring end-to-end: [`cluv_integration.py`](examples/cluv_integration.py) (policy + render) and [`xgenius_integration.py`](examples/xgenius_integration.py) (policy-only, when the host tool keeps its own renderer).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

pysalvo-0.2.0/README.md

@@ -0,0 +1,105 @@
+# salvo
+
+Policy and render library for SLURM. salvo turns a `JobSpec` into byte-stable sbatch text and decides what to do when a job hits OOM or gets preempted. It does not move code to the cluster, does not open SSH connections, and is not a runner. For transport, pair it with [cluv](https://github.com/mila-iqia/cluv) or invoke `sbatch` directly.
+
+## Install
+
+    pip install pysalvo
+
+Two CLI commands ship for diagnostics and one-shot rendering. Everything else is meant to be imported.
+
+    salvo doctor                                 # topology, ssh alias hygiene, manifest freshness
+    salvo render spec.yaml --cluster mila        # JobSpec YAML to sbatch text on stdout
+
+## Render
+
+```python
+from salvo import JobSpec, render
+
+spec = JobSpec(
+    name="train",
+    cmd=["python", "train.py"],
+    gpus=1, cpus=8, mem="32G", time="2h",
+    on_oom=["bump_mem(1.5x, max=128G)", "fail"],
+)
+
+sbatch_text = render(
+    spec,
+    cluster_id="mila",
+    account="mila",
+    partition="unkillable",
+)  # str, byte-stable, no side effects
+```
+
+Same JobSpec, same cluster, same inputs, same bytes every run. Useful when you need to audit what was actually submitted six months later.
+
+If you leave `account` and `partition` off, salvo picks them via `salvo.dispatch` by shelling out to `squeue` for live capacity. That path only works on a SLURM login node; library callers (cluv, xgenius) should pass both explicitly to keep `render()` pure.
+
+## OOM policy
+
+```python
+from salvo.policy import parse, apply_oom, OomContext
+
+steps = parse(["bump_mem(1.5x, max=128G)", "escalate_partition", "fail"])
+
+new_spec, action = apply_oom(prev_spec, OomContext(kind="cpu", max_rss_mb=33_500))
+# new_spec is a fresh JobSpec with bumped mem, or None if the policy says fail
+```
+
+The DSL is intentionally small. Steps run in order until one applies:
+
+- `bump_mem(<factor>x, max=<size>)` — multiplicative bump, capped
+- `escalate_partition` — clear partition so the next render picks a larger tier
+- `fail` — terminal
+- `bump_gpus(...)`, `callback(...)` — parse today, execute in a later release
+
+## Cluster topology
+
+Five presets ship in `salvo/topology/presets/`: `mila`, `rorqual`, `narval`, `beluga`, `cedar`. More DRAC clusters land as YAMLs are contributed. Each YAML lists accounts, partitions, and capacity rules.
+
+```python
+from salvo.topology import load_preset, list_presets
+
+list_presets()                      # ['beluga', 'cedar', 'mila', 'narval', 'rorqual']
+cluster = load_preset("mila")       # ClusterTopology
+```
+
+Contributing a new cluster is one YAML file. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Decorator (optional, Python-native)
+
+If you'd rather write a function than a YAML spec:
+
+```python
+from salvo import cluster
+
+@cluster.submit(gpus=1, cpus=8, mem="32G", time="2h",
+                on_oom=["bump_mem(1.5x, max=128G)", "fail"])
+def train(seed: int):
+    ...
+
+handle = train.submit(seed=42)
+```
+
+`train.submit(...)` runs the local-sbatch convenience path: it renders, calls `sbatch`, and returns a handle. Skip the decorator if you're embedding salvo inside another tool's submit flow; just call `render()` and let that tool do the submission.
+
+## Use with cluv
+
+cluv handles SSH, code sync, and the `sbatch` call. salvo handles the policy. The natural composition is cluv importing salvo's policy library when a user opts in:
+
+```toml
+# in your project's pyproject.toml
+[tool.cluv.retry]
+on_oom = ["bump_mem(1.5x, max=128G)", "fail"]
+max_hops = 5
+```
+
+This is a proposal, not a shipped feature in cluv. An upstream issue is in draft.
+
+## Use with anything that calls sbatch
+
+salvo has no SSH or async dependencies. It is a pydantic + stdlib library. Any tool that runs `sbatch` can import `salvo.render`, `salvo.policy.apply_oom`, and `salvo.topology.load_preset` independently. Two runnable examples under [`examples/`](examples/) show the wiring end-to-end: [`cluv_integration.py`](examples/cluv_integration.py) (policy + render) and [`xgenius_integration.py`](examples/xgenius_integration.py) (policy-only, when the host tool keeps its own renderer).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

pysalvo-0.2.0/SECURITY.md

@@ -0,0 +1,5 @@
+# Security policy
+
+If you find a vulnerability in salvo, please report it privately rather than opening a public issue. Open a GitHub security advisory on this repo, or email the maintainer listed in `pyproject.toml`. Expect an acknowledgement within 7 days.
+
+salvo dispatches user code to SLURM clusters via `sbatch`. It does not transmit credentials, secrets, or job payloads to any third party. The only network calls are SSH/scp/rsync against clusters the operator configures.

pysalvo-0.2.0/examples/cluv_integration.py

@@ -0,0 +1,83 @@
+"""End-to-end example: how cluv would call salvo as its retry-policy library.
+
+A cluv maintainer should be able to read this file on a laptop and trust
+that wiring salvo into cluv's submit flow is a small, well-defined change.
+It walks the natural composition described in salvo's README ("Use with
+cluv"): parse the on_oom DSL from pyproject, build a JobSpec from values
+cluv already has, run apply_oom on a synthetic OOM, and render the bumped
+spec to sbatch text. No SLURM, no network, no subprocess — just stdlib +
+pydantic. Run with: ``python examples/cluv_integration.py``.
+"""
+
+from __future__ import annotations
+
+from salvo import JobSpec, render
+from salvo.policy import OomContext, apply_oom, parse
+
+
+def main() -> None:
+    # 1. Parse the policy DSL from a string list. In real cluv this list
+    #    comes from `[tool.cluv.retry].on_oom` in the user's pyproject.toml.
+    on_oom_dsl: list[str] = ["bump_mem(1.5x, max=128G)", "fail"]
+    steps = parse(on_oom_dsl)
+    print(f"parsed {len(steps)} policy step(s): {[type(s).__name__ for s in steps]}")
+
+    # 2. Build a minimal JobSpec from values cluv already has. cluv knows
+    #    the entrypoint, gpu/cpu ask, env-var-style mem string, and the
+    #    user's on_oom list — exactly what JobSpec needs.
+    spec = JobSpec(
+        name="train",
+        cmd=["python", "train.py"],
+        gpus=1,
+        cpus=8,
+        mem="32G",
+        time="2h",
+        on_oom=on_oom_dsl,
+        max_hops=5,
+    )
+
+    # 6. Walk all three hops of the bump_mem ladder so the example shows
+    #    the policy doing something across resubmissions, not just one call.
+    #    32G -> 48G -> 72G -> 108G (1.5x each, capped at 128G).
+    current: JobSpec | None = spec
+    for hop in range(1, 4):
+        assert current is not None  # narrowing for type-checkers
+        mem_before = current.mem
+
+        # 3. Synthesize an OOM context. cluv builds this from the job state
+        #    it already tracks (sacct max_rss, tail of stderr, cpu/gpu class).
+        ctx = OomContext(
+            kind="cpu",
+            max_rss_mb=current.mem_mb(),  # observed RSS pinned to current ask
+            log_excerpt="slurmstepd: error: Detected 1 oom_kill event",
+        )
+
+        # 4. Apply the policy. Two outcomes:
+        #      (new_spec, "bump_mem")       -> resubmit with new_spec.mem
+        #      (None,     "fail")           -> stop, surface to user
+        new_spec, action = apply_oom(current, ctx)
+        if new_spec is None:
+            print(f"hop {hop}: action={action!r}  mem {mem_before} -> (stop)")
+            break
+
+        print(f"hop {hop}: action={action!r}  mem {mem_before} -> {new_spec.mem}")
+        current = new_spec
+
+    # 5. Render the final bumped spec to sbatch text. With both account and
+    #    partition supplied this is pure: no squeue, no SLURM, no I/O. cluv
+    #    would write this string to a file and `sbatch` it; here we just
+    #    print the header so the audit trail is visible.
+    assert current is not None
+    sbatch_text = render(
+        current,
+        cluster_id="mila",
+        account="mila",
+        partition="unkillable",
+    )
+    print("\nrendered sbatch (header only):")
+    for line in sbatch_text.splitlines()[:8]:
+        print(f"  {line}")
+
+
+if __name__ == "__main__":
+    main()

pysalvo-0.2.0/examples/xgenius_integration.py

@@ -0,0 +1,87 @@
+"""End-to-end example: how xgenius would call salvo as its OOM-policy library.
+
+xgenius already has its own sbatch renderer (Jinja-style ``{{PLACEHOLDER}}``
+templates in ``xgenius/templates.py``) and its own SafetyValidator with a
+fixed ``max_memory_per_job`` ceiling. It has no dynamic OOM handling: an
+OOM-killed job is observed by the watcher daemon but no corrective action
+is taken. salvo.policy fills exactly that gap. This example shows the
+policy-only integration path: xgenius keeps its template renderer; only
+the watcher imports salvo. No SLURM, no network, no subprocess — just
+stdlib + pydantic. Run with: ``python examples/xgenius_integration.py``.
+"""
+
+from __future__ import annotations
+
+from salvo import JobSpec
+from salvo.policy import OomContext, OomDecision, apply_oom, parse
+
+
+def main() -> None:
+    # 1. Parse the policy from a future xgenius config knob, e.g. a new
+    #    ``[retry] on_oom = [...]`` table in ``xgenius.toml``. Validation
+    #    happens here: an unknown step raises ValueError pointing at the
+    #    bad string, before any job runs.
+    on_oom_dsl: list[str] = ["bump_mem(2x, max=80G)", "fail"]
+    steps = parse(on_oom_dsl)
+    print(f"parsed {len(steps)} policy step(s): {[type(s).__name__ for s in steps]}")
+
+    # 2. The xgenius watcher detects OUT_OF_MEMORY for an experiment.
+    #    It already knows the experiment's gpu/cpu/mem/walltime ask
+    #    (from xgenius.toml + the running job record). Wrap that in a
+    #    JobSpec — JobSpec is the only salvo type the watcher needs to
+    #    build. The cmd field is unused by apply_oom; pass a sentinel.
+    experiment_gpus = 1
+    experiment_cpus = 4
+    experiment_mem = "16G"
+    experiment_walltime = "4h"
+
+    spec = JobSpec(
+        name="experiment-42",
+        cmd=["xgenius-runner"],
+        gpus=experiment_gpus,
+        cpus=experiment_cpus,
+        mem=experiment_mem,
+        time=experiment_walltime,
+        on_oom=on_oom_dsl,
+    )
+
+    # 3. Synthesize an OomContext from what the watcher already polls.
+    #    xgenius's COMPLETION_EPILOG drops a trap-based marker on OOM;
+    #    MaxRSS is read via sacct the same way cluv does. ``kind`` is
+    #    "gpu" only when the job asked for gpus AND the OOM came from
+    #    GPU memory exhaustion. For CPU-side OOM on a GPU job, "cpu" is
+    #    still the right kind because that is the resource being bumped.
+    observed_max_rss_mb = 15_900
+    ctx = OomContext(
+        kind="cpu",
+        max_rss_mb=observed_max_rss_mb,
+        log_excerpt="slurmstepd: error: Detected 1 oom_kill event",
+    )
+
+    # 4. Ask salvo what to do. The return is a NamedTuple — both
+    #    attribute and tuple-unpack work, so the watcher can pick
+    #    whichever style reads cleaner in its existing code.
+    decision: OomDecision = apply_oom(spec, ctx)
+    if decision.new_spec is None:
+        print(f"policy terminated: action={decision.action!r} — escalate to human")
+        return
+
+    # 5. xgenius now re-runs its own template renderer with the bumped
+    #    memory string. salvo does not render xgenius templates; the
+    #    watcher just substitutes ``new_spec.mem`` back into the params
+    #    dict it already builds in ``xgenius/jobs.py:submit``.
+    new_params = {
+        "memory": decision.new_spec.mem,  # "32768M" after 16G * 2
+        "gpus": decision.new_spec.gpus,
+        "cpus": decision.new_spec.cpus,
+        "walltime": decision.new_spec.time,
+    }
+    print(f"action={decision.action!r}")
+    print(f"  mem  {experiment_mem} -> {decision.new_spec.mem}")
+    print("  hand back to xgenius template renderer with params:")
+    for k, v in new_params.items():
+        print(f"    {k}={v!r}")
+
+
+if __name__ == "__main__":
+    main()

pysalvo-0.2.0/pyproject.toml

@@ -0,0 +1,79 @@
+[project]
+name = "pysalvo"
+version = "0.2.0"
+description = "Render + policy library for SLURM JobSpecs (Mila + DRAC clusters)"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "W" }]
+keywords = ["slurm", "hpc", "sbatch", "mila", "drac", "alliance-canada"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: System :: Clustering",
+    "Topic :: System :: Distributed Computing",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.6",
+    "typer>=0.12",
+    "pyyaml>=6.0",
+    "rich>=13.7",
+    "tomli-w>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/wietzesuijker/salvo"
+Source = "https://github.com/wietzesuijker/salvo"
+Issues = "https://github.com/wietzesuijker/salvo/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "hypothesis>=6.100",
+    "ruff>=0.5",
+    "mypy>=1.10",
+    "pre-commit>=3.7",
+    "types-pyyaml",
+]
+mila = []
+drac = []
+all = ["pysalvo[mila,drac]"]
+
+[project.scripts]
+salvo = "salvo.cli:app"
+
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/salvo"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src/salvo"]
+disallow_untyped_decorators = false
+
+[tool.pytest.ini_options]
+addopts = "-ra --strict-markers --cov=salvo --cov-report=term-missing --cov-fail-under=80"
+testpaths = ["tests"]