freesolo-flash-dev 1.0.44__tar.gz → 1.0.45__tar.gz

{freesolo_flash_dev-1.0.44 → freesolo_flash_dev-1.0.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freesolo-flash-dev
-Version: 1.0.44
+Version: 1.0.45
 Summary: Flash — managed LoRA post-training (SFT/GRPO/OPD) for Freesolo environments, driven by the `flash` CLI
 Project-URL: Homepage, https://github.com/freesolo-co/flash
 Project-URL: Repository, https://github.com/freesolo-co/flash

{freesolo_flash_dev-1.0.44 → freesolo_flash_dev-1.0.45}/flash/cli/training_doc.py

@@ -697,6 +697,39 @@ on a beyond-noise improvement.
 
 ---
 
+## Multi-GPU training (`gpu.count > 1`)
+
+Flash trains on one card by default. The default `trl` backend is single-process and never
+reads `gpu.count`, so raising the count alone would rent n cards and train on one — submit
+rejects that rather than billing for idle hardware.
+
+To shard one job across several cards, select the `verl` backend for the phase you are running:
+
+```toml
+[gpu]
+type = "B200"
+count = 4
+# provider must also be pinned: not every provider puts all n cards on ONE machine, and
+# submit names the ones that qualify when it rejects an unpinned multi-gpu spec.
+
+[worker_env]
+FLASH_SFT_BACKEND = "verl"   # SFT
+# FLASH_RL_BACKEND  = "verl"   # GRPO  (the key is RL, not GRPO)
+# FLASH_OPD_BACKEND = "verl"   # OPD
+```
+
+One key per phase, and GRPO's is `FLASH_RL_BACKEND`. The verl worker launches one rank per
+card with Ulysses sequence parallelism.
+
+The verl GRPO backend covers single-turn, non-tool, non-multimodal runs; multi-turn, tool, and
+image-prompt environments stay on `trl` (which is single-GPU). Warm-starting with
+`init_from_adapter` while `kl_penalty_coef > 0` is also `trl`-only: verl computes its KL
+reference with adapters disabled, so the reference would be the bare base model instead of your
+SFT adapter, pulling the policy back toward base. Every one of these raises at startup rather
+than quietly training on a different contract.
+
+---
+
 ## Command reference
 
 ```bash

{freesolo_flash_dev-1.0.44 → freesolo_flash_dev-1.0.45}/flash/runner/__init__.py

@@ -1187,6 +1187,15 @@ _MULTI_GPU_BACKENDS: frozenset[str] = frozenset({"verl"})
 _MULTI_GPU_PROVIDERS: frozenset[str] = frozenset({"runpod"})
 
 
+def _backend_env_key(spec: JobSpec) -> str:
+    """the [worker_env] key that selects this spec's training backend.
+
+    one definition so the gate's remedy cannot name a different key than the resolver reads: the
+    phase mapping is not derivable from the algorithm (grpo -> FLASH_RL_BACKEND).
+    """
+    return f"FLASH_{spec.phase.upper()}_BACKEND"
+
+
 def _effective_backend(spec: JobSpec) -> str:
     """the training backend this spec will actually run, as the worker resolves it.
 
@@ -1195,7 +1204,7 @@ def _effective_backend(spec: JobSpec) -> str:
     empty dict and forwards a fixed credential allowlist, never the ambient control-plane env. so the
     backend is a property of the SPEC and the gate can read it here rather than guessing.
     """
-    key = f"FLASH_{spec.phase.upper()}_BACKEND"
+    key = _backend_env_key(spec)
     worker_env = getattr(spec, "worker_env", None) or {}
     for name, value in worker_env.items():
         if str(name).upper() == key:
@@ -1215,10 +1224,16 @@ def _require_supported_gpu_count(spec: JobSpec) -> None:
         return
     backend = _effective_backend(spec)
     if backend not in _MULTI_GPU_BACKENDS:
+        # name the key that actually enables sharding. the backend is selected only through
+        # [worker_env], which no other error or doc mentions, so a message that offers just
+        # "set gpu.count to 1" leaves multi-gpu undiscoverable.
+        key = _backend_env_key(spec)
+        sharding = ", ".join(sorted(_MULTI_GPU_BACKENDS))
         raise ValueError(
             f"multi-gpu training (gpu.count={count}) is not supported by the {backend!r} backend "
             f"for algorithm {spec.algorithm!r}; it trains in a single process and would leave "
-            f"{count - 1} rented card(s) idle. set gpu.count to 1"
+            f"{count - 1} rented card(s) idle. set gpu.count to 1, or select a sharding backend "
+            f'with [worker_env] {key} = "{sharding}"'
         )
     provider = (getattr(spec.gpu, "provider", "") or "").strip().lower()
     if provider not in _MULTI_GPU_PROVIDERS:

{freesolo_flash_dev-1.0.44 → freesolo_flash_dev-1.0.45}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "freesolo-flash-dev"
-version = "1.0.44"
+version = "1.0.45"
 description = "Flash — managed LoRA post-training (SFT/GRPO/OPD) for Freesolo environments, driven by the `flash` CLI"
 readme = "README.md"
 # RunPod Flash supports Python 3.11-3.12 (not 3.13 yet).
@@ -116,7 +116,7 @@ artifacts = ["flash/py.typed"]
 # auto-published by .github/workflows/publish-dev.yml: a push to `dev` whose version isn't yet on
 # PyPI publishes it; pushes that don't change it find it already published and no-op. So cutting a
 # dev-channel release = bump this (and [project].version) and merge to `dev`.
-version = "1.0.44"
+version = "1.0.45"
 
 [tool.pytest.ini_options]
 pythonpath = ["."]

{freesolo_flash_dev-1.0.44 → freesolo_flash_dev-1.0.45}/tests/test_multi_gpu_gate.py

@@ -110,3 +110,24 @@ def test_run_training_gates_effective_spec_on_recovery():
     # before any provisioning (the gate precedes the first get_status/allocation touch).
     with pytest.raises(ValueError, match="multi-gpu training"):
         _run_training(_spec(2), io.StringIO(), prior_cost=0.0)
+
+
+@pytest.mark.parametrize(
+    ("algorithm", "key"),
+    [("sft", "FLASH_SFT_BACKEND"), ("grpo", "FLASH_RL_BACKEND"), ("opd", "FLASH_OPD_BACKEND")],
+)
+def test_gate_message_names_the_key_that_enables_sharding(algorithm, key):
+    from flash import runner
+
+    # [worker_env] is the ONLY route to a sharding backend, and the phase key is not guessable from
+    # the algorithm (grpo -> FLASH_RL_BACKEND). a message offering only "set gpu.count to 1" leaves
+    # multi-gpu undiscoverable, so assert the remedy travels with the rejection.
+    # match the backend rejection specifically: the gate also raises for gpu.provider, and that
+    # path carries no backend key, so a bare raises() would pass while checking nothing.
+    with pytest.raises(ValueError, match="multi-gpu training") as excinfo:
+        runner._require_supported_gpu_count(_spec(4, algorithm))
+
+    message = str(excinfo.value)
+    assert key in message
+    assert "verl" in message
+    assert "worker_env" in message

{freesolo_flash_dev-1.0.44 → freesolo_flash_dev-1.0.45}/uv.lock

@@ -1025,7 +1025,7 @@ wheels = [
 
 [[package]]
 name = "freesolo-flash"
-version = "1.0.44"
+version = "1.0.45"
 source = { editable = "." }
 
 [package.optional-dependencies]