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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freesolo-flash-dev
-Version: 1.0.45
+Version: 1.0.46
 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.45 → freesolo_flash_dev-1.0.46}/flash/engine/worker/opd_verl.py

@@ -71,6 +71,8 @@ from flash.engine.worker.verl_common import (
     clamp_engine_len,
     latest_global_step_dir,
     model_max_position_embeddings,
+    parse_wandb_link,
+    render_wandb_link_shim,
     resolve_verl_python,
     run_verl_training,
 )
@@ -2344,13 +2346,14 @@ def run_opd_verl(spec=None) -> None:
     entry_path = os.path.join(shim_dir, "flash_opd_verl_entry.py")
     with open(entry_path, "w", encoding="utf-8") as file:
         file.write("import verl\nfrom flash_opd_verl_plugin import main\nmain()\n")
+    opd_shim_source = _render_opd_sitecustomize(
+        save_at_steps=knobs.save_at_steps,
+        total_steps=update_horizon,
+    )
+    if "wandb" in loggers:
+        opd_shim_source += render_wandb_link_shim()
     with open(os.path.join(shim_dir, "sitecustomize.py"), "w", encoding="utf-8") as file:
-        file.write(
-            _render_opd_sitecustomize(
-                save_at_steps=knobs.save_at_steps,
-                total_steps=update_horizon,
-            )
-        )
+        file.write(opd_shim_source)
 
     resume_step, resume_state = _restore_verl_resume(
         local_dir,
@@ -2451,9 +2454,13 @@ def run_opd_verl(spec=None) -> None:
         )
         command = [python_bin, entry_path, *overrides]
         progress = {"step": resume_step, "loss": None}
+        wandb_link: dict[str, str | None] = {}
 
         def on_line(line: str) -> None:
             watcher.raise_if_failed()
+            link = parse_wandb_link(line)
+            if link is not None:
+                wandb_link.update(link)
             step_match = _VERL_STEP_RE.search(line)
             if step_match is None:
                 return
@@ -2669,6 +2676,10 @@ def run_opd_verl(spec=None) -> None:
                 "resumed": bool(resume_step),
                 "wandb_project": project_name if "wandb" in loggers else None,
                 "wandb_run_name": experiment_name if "wandb" in loggers else None,
+                # the sdk's link_wandb reads notes["wandb_url"]; trl gets it from the parent's live
+                # wandb.run, verl from the child marker (see verl_common.render_wandb_link_shim).
+                "wandb_url": wandb_link.get("wandb_url"),
+                "wandb_id": wandb_link.get("wandb_id"),
             },
         )
     finally:

{freesolo_flash_dev-1.0.45 → freesolo_flash_dev-1.0.46}/flash/engine/worker/rl_verl.py

@@ -52,6 +52,8 @@ from flash.engine.worker.verl_common import (
     agent_loop_workers,
     clamp_engine_len,
     model_max_position_embeddings,
+    parse_wandb_link,
+    render_wandb_link_shim,
     resolve_verl_python,
     verl_supports_rollout_field,
 )
@@ -370,6 +372,8 @@ def _build_verl_train_notes(
     fp8_kv: bool = False,
     wandb_project: str | None = None,
     wandb_run_name: str | None = None,
+    wandb_url: str | None = None,
+    wandb_id: str | None = None,
 ) -> dict:
     return {
         "backend": "verl",
@@ -419,6 +423,10 @@ def _build_verl_train_notes(
         "ppo_max_token_len_per_gpu": inp["engine_len"],
         "wandb_project": wandb_project,
         "wandb_run_name": wandb_run_name,
+        # the sdk's link_wandb reads notes["wandb_url"]; trl gets it from the parent's live
+        # wandb.run, verl from the child marker (see verl_common.render_wandb_link_shim).
+        "wandb_url": wandb_url,
+        "wandb_id": wandb_id,
         "grpo_recipe": {
             "kl_coef": inp["kl_coef"],
             "entropy_quantile": inp["entropy_quantile"],
@@ -1420,6 +1428,10 @@ def run_rl_verl():
             render_stop_sequences_shim(inp["stop_sequences"]),
             render_structured_outputs_shim(inp["structured_outputs"]),
             render_exact_save_steps_shim(inp["save_at_steps"], inp["steps"]),
+            # gated on the key rather than the resolved logger list: that list needs python_bin,
+            # which is resolved after this file is written. the shim is inert either way -- it only
+            # fires when verl actually calls wandb.init, which requires wandb in the logger list.
+            render_wandb_link_shim() if os.environ.get("WANDB_API_KEY") else "",
         )
         if part
     )
@@ -1433,6 +1445,8 @@ def run_rl_verl():
     # rolling buffer of recent (completion, score) so the training loop can dump one sample per step
     # to the flash log, matching the trl path's #607 per-step completion dump.
     recent_samples: list[tuple[str, float]] = []
+    # filled from the child's marker line; stays empty when wandb is off (see render_wandb_link_shim).
+    wandb_link: dict[str, str | None] = {}
     _samples_lock = threading.Lock()
 
     def _score(index: int, solution_str: str) -> float:
@@ -1560,6 +1574,9 @@ def run_rl_verl():
             try:
                 for line in proc.stdout:
                     print(f"[verl] {line}", end="", flush=True)
+                    link = parse_wandb_link(line)
+                    if link is not None:
+                        wandb_link.update(link)
                     m = step_re.search(line)
                     if m:
                         step_box[0] = int(m.group(1))
@@ -1670,5 +1687,7 @@ def run_rl_verl():
             fp8_kv=fp8_kv,
             wandb_project=project_name if "wandb" in loggers else None,
             wandb_run_name=experiment_name if "wandb" in loggers else None,
+            wandb_url=wandb_link.get("wandb_url"),
+            wandb_id=wandb_link.get("wandb_id"),
         ),
     )

{freesolo_flash_dev-1.0.45 → freesolo_flash_dev-1.0.46}/flash/engine/worker/sft_verl.py

@@ -42,6 +42,8 @@ from flash.engine.worker.sft import (
 from flash.engine.worker.verl_common import (
     export_peft_adapter,
     latest_global_step_dir,
+    parse_wandb_link,
+    render_wandb_link_shim,
     resolve_verl_python,
     run_verl_training,
     stamp_adapter_dir_provenance,
@@ -1282,6 +1284,8 @@ def run_sft_verl(spec=None) -> None:
         total_steps=update_horizon,
         reentrant_gradient_checkpointing=reentrant_gradient_checkpointing,
     )
+    if "wandb" in loggers:
+        shim_source += render_wandb_link_shim()
     with open(os.path.join(shim_dir, "sitecustomize.py"), "w", encoding="utf-8") as file:
         file.write(shim_source)
     with open(custom_dataset_path, "w", encoding="utf-8") as file:
@@ -1327,12 +1331,16 @@ def run_sft_verl(spec=None) -> None:
         resume_step,
     )
     loraplus_applied = resume_step >= update_horizon
+    wandb_link: dict[str, str | None] = {}
 
     def on_line(line: str) -> None:
         nonlocal loraplus_applied
         watcher.raise_if_failed()
         if _LORAPLUS_READY_MARKER in line:
             loraplus_applied = True
+        link = parse_wandb_link(line)
+        if link is not None:
+            wandb_link.update(link)
         step_match = _VERL_STEP_RE.search(line)
         if step_match is None:
             return
@@ -1458,5 +1466,9 @@ def run_sft_verl(spec=None) -> None:
             "ulysses_sequence_parallel_size": gpu_count,
             "wandb_project": project_name if "wandb" in loggers else None,
             "wandb_run_name": experiment_name if "wandb" in loggers else None,
+            # the sdk's link_wandb reads notes["wandb_url"]; trl gets it from the parent's live
+            # wandb.run, verl from the child marker (see verl_common.render_wandb_link_shim).
+            "wandb_url": wandb_link.get("wandb_url"),
+            "wandb_id": wandb_link.get("wandb_id"),
         },
     )

{freesolo_flash_dev-1.0.45 → freesolo_flash_dev-1.0.46}/flash/engine/worker/verl_common.py

@@ -317,3 +317,77 @@ def _kill_process_group(proc: subprocess.Popen) -> None:
         os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
     with contextlib.suppress(subprocess.TimeoutExpired):
         proc.wait(timeout=10)
+
+
+# --------------------------- w&b run link (all three verl backends) ---------------------------
+# trl spreads wandb_run_info() into its notes, giving the sdk's link_wandb a clickable
+# notes["wandb_url"]. verl calls wandb.init INSIDE the training subprocess, so the flash parent's
+# wandb.run is None and that spread would be a silent no-op. the url is not derivable up here
+# either: it needs entity/project/runs/<wandb-generated-id>, and flash only knows the project and
+# its own run NAME. so the child reports it back over the marker channel the parent already scans.
+FLASH_WANDB_LINK_MARKER = "FLASH_WANDB_LINK"
+
+_WANDB_LINK_RE = re.compile(rf"{FLASH_WANDB_LINK_MARKER}\s+(\{{.*\}})\s*$")
+
+
+def render_wandb_link_shim() -> str:
+    """child-side sitecustomize fragment that reports the live w&b run's url and id.
+
+    wraps wandb.init rather than reading wandb.run at import time: sitecustomize runs long before
+    verl's tracking module initializes the run, so anything read here would always be None.
+
+    never raises. wandb is optional and a logging link must not be able to abort paid training, so
+    every failure path leaves the run unlinked instead of dead.
+    """
+    return f'''
+# --- flash: report the w&b run link to the parent (see verl_common.render_wandb_link_shim) ---
+try:
+    import json as _flash_wandb_json
+
+    import wandb as _flash_wandb
+
+    _flash_wandb_init = _flash_wandb.init
+
+    def _flash_wandb_init_reporting(*args, **kwargs):
+        _run = _flash_wandb_init(*args, **kwargs)
+        try:
+            _url = getattr(_run, "url", None)
+            _id = getattr(_run, "id", None)
+            if _url:
+                print(
+                    "{FLASH_WANDB_LINK_MARKER} "
+                    + _flash_wandb_json.dumps({{"wandb_url": _url, "wandb_id": _id}}),
+                    flush=True,
+                )
+        except Exception:
+            pass
+        return _run
+
+    _flash_wandb.init = _flash_wandb_init_reporting
+except Exception:
+    pass
+'''
+
+
+def parse_wandb_link(line: str) -> dict | None:
+    """the {{wandb_url, wandb_id}} a marker line carries, or None for every other line.
+
+    returns None rather than raising on a malformed payload: this parses child stdout, and a
+    truncated or interleaved line under multi-rank logging must not take down the run.
+    """
+    match = _WANDB_LINK_RE.search(line)
+    if match is None:
+        return None
+    try:
+        payload = json.loads(match.group(1))
+    except ValueError:
+        return None
+    if not isinstance(payload, dict):
+        return None
+    url = payload.get("wandb_url")
+    # https only: the sdk renders this as a clickable dashboard link, and child stdout also carries
+    # rollout text, so the field must not be able to become an arbitrary scheme.
+    if not isinstance(url, str) or not url.startswith("https://"):
+        return None
+    wandb_id = payload.get("wandb_id")
+    return {"wandb_url": url, "wandb_id": wandb_id if isinstance(wandb_id, str) else None}

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

@@ -1,6 +1,6 @@
 [project]
 name = "freesolo-flash-dev"
-version = "1.0.45"
+version = "1.0.46"
 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.45"
+version = "1.0.46"
 
 [tool.pytest.ini_options]
 pythonpath = ["."]

{freesolo_flash_dev-1.0.45 → freesolo_flash_dev-1.0.46}/tests/test_rl_verl.py

@@ -322,48 +322,8 @@ def test_resolver_clamps_prompt_budget_with_the_engine(monkeypatch):
     # UNCLAMPED context. those prompts plus the completion allowance overflow the engine vllm was
     # actually given, so they die at rollout instead of training on the shorter context. every
     # length must descend from one clamped value.
-    from flash.engine.worker._pkg import W
-    from flash.spec import JobSpec
-
-    class _Env:
-        multi_turn = False
-        is_tool_env = False
-
-        def dataset(self):
-            return [{"index": i} for i in range(8)]
-
-        def prompt_messages(self, ex):
-            return [{"role": "user", "content": f"question {ex['index']}"}]
-
-    class _Tokenizer:
-        pad_token = None
-        eos_token = "<eos>"
-
-        def apply_chat_template(self, messages, **kwargs):
-            return messages[0]["content"]
-
-        def __call__(self, text, **kwargs):
-            return SimpleNamespace(input_ids=[1])
-
-    spec = JobSpec.from_dict(
-        {
-            "model": "Qwen/Qwen3.5-0.8B",
-            "algorithm": "grpo",
-            # asks for twice the architecture's context.
-            "train": {"batch_size": 4, "epochs": 1, "max_context_tokens": 65536},
-        }
-    )
-    monkeypatch.setattr(W, "JOB_SPEC", spec, raising=False)
-    monkeypatch.setattr(W, "SEED", 42, raising=False)
-    monkeypatch.setattr(W, "THINKING", False, raising=False)
-    monkeypatch.setattr(W, "require_active_env", lambda: _Env(), raising=False)
-    monkeypatch.setattr(W, "grpo_overrides", lambda: {}, raising=False)
-    monkeypatch.setattr(W, "grpo_mask_truncated_completions", lambda train: False, raising=False)
-    monkeypatch.setattr(W, "load_tokenizer", lambda *args, **kwargs: _Tokenizer(), raising=False)
-    monkeypatch.setattr(rl_verl, "seed_training_rngs", lambda seed: None)
-    monkeypatch.setattr(rl_verl, "model_max_position_embeddings", lambda *a, **k: 32768)
-
-    inp = rl_verl._resolve_single_turn_inputs()
+    # asks for twice the architecture's context (model_max_position_embeddings is pinned to 32768).
+    inp = _capability_resolve(monkeypatch, _capability_env(), train={"max_context_tokens": 65536})
     assert inp["engine_len"] == 32768
     # the prompt filter's budget is carved out of the clamped engine, not the requested 65536.
     assert inp["max_prompt_len"] + inp["max_completion"] == 32768
@@ -388,47 +348,12 @@ def test_resolver_clamps_prompt_budget_with_the_engine(monkeypatch):
 
 def _save_steps_inputs(monkeypatch, *, save_at_steps=None, save_every=None, max_steps=100):
     """resolve grpo verl inputs for a job with (or without) exact save steps."""
-    from flash.engine.worker._pkg import W
-    from flash.spec import JobSpec
-
-    class _Env:
-        multi_turn = False
-        is_tool_env = False
-
-        def dataset(self):
-            return [{"index": i} for i in range(8)]
-
-        def prompt_messages(self, ex):
-            return [{"role": "user", "content": f"question {ex['index']}"}]
-
-    class _Tokenizer:
-        pad_token = None
-        eos_token = "<eos>"
-
-        def apply_chat_template(self, messages, **kwargs):
-            return messages[0]["content"]
-
-        def __call__(self, text, **kwargs):
-            return SimpleNamespace(input_ids=[1])
-
-    train: dict = {"batch_size": 4, "epochs": 1, "max_steps": max_steps}
+    train: dict = {"max_steps": max_steps}
     if save_at_steps is not None:
         train["save_at_steps"] = list(save_at_steps)
     if save_every is not None:
         train["save_every"] = save_every
-    spec = JobSpec.from_dict(
-        {"model": "Qwen/Qwen3.5-0.8B", "algorithm": "grpo", "train": train}
-    )
-    monkeypatch.setattr(W, "JOB_SPEC", spec, raising=False)
-    monkeypatch.setattr(W, "SEED", 42, raising=False)
-    monkeypatch.setattr(W, "THINKING", False, raising=False)
-    monkeypatch.setattr(W, "require_active_env", lambda: _Env(), raising=False)
-    monkeypatch.setattr(W, "grpo_overrides", lambda: {}, raising=False)
-    monkeypatch.setattr(W, "grpo_mask_truncated_completions", lambda train: False, raising=False)
-    monkeypatch.setattr(W, "load_tokenizer", lambda *args, **kwargs: _Tokenizer(), raising=False)
-    monkeypatch.setattr(rl_verl, "seed_training_rngs", lambda seed: None)
-    monkeypatch.setattr(rl_verl, "model_max_position_embeddings", lambda *a, **k: 32768)
-    return rl_verl._resolve_single_turn_inputs()
+    return _capability_resolve(monkeypatch, _capability_env(), train=train)
 
 
 def test_save_freq_is_the_gcd_so_verl_lands_on_every_required_step(monkeypatch):
@@ -1343,3 +1268,119 @@ def test_train_notes_report_token_bounded_batching_as_unset_not_fabricated():
     assert notes["ppo_max_token_len_per_gpu"] == 4096
     # trl pins vllm's prefill batch because it hardcodes 4096; this path sets no such override.
     assert notes["vllm_max_num_batched_tokens"] is None
+
+
+# ------------------- capability guards: the four specs verl grpo refuses -------------------
+# these four raises are the ONLY thing standing between a trl-supported job and a verl run that
+# trains on a different contract. they had no regression coverage: every resolver test above drives
+# the happy path, so deleting any guard left the suite green. each test below asserts one rejection
+# by its own message, because a bare pytest.raises(RuntimeError) passes on any of the ~20 other
+# raises in this resolver.
+
+
+def _capability_env(*, multi_turn=False, is_tool_env=False, images=False):
+    """a minimal single-turn text env, optionally flipped to a shape verl grpo rejects."""
+
+    class _Env:
+        def __init__(self):
+            self.multi_turn = multi_turn
+            self.is_tool_env = is_tool_env
+
+        def dataset(self):
+            return [{"index": i} for i in range(8)]
+
+        def prompt_messages(self, ex):
+            if images:
+                # record_has_images matches an image content BLOCK, so build the real shape rather
+                # than a sentinel key the guard would not see.
+                return [
+                    {
+                        "role": "user",
+                        "content": [
+                            {"type": "text", "text": f"question {ex['index']}"},
+                            {"type": "image_url", "image_url": {"url": "https://x/y.png"}},
+                        ],
+                    }
+                ]
+            return [{"role": "user", "content": f"question {ex['index']}"}]
+
+    return _Env()
+
+
+def _capability_resolve(monkeypatch, env, train=None, overrides=None):
+    """run the resolver against one env, with everything else on the supported path."""
+    from flash.engine.worker._pkg import W as _PkgW
+    from flash.spec import JobSpec
+
+    class _Tokenizer:
+        pad_token = None
+        eos_token = "<eos>"
+
+        def apply_chat_template(self, messages, **kwargs):
+            return "prompt"
+
+        def __call__(self, text, **kwargs):
+            return SimpleNamespace(input_ids=[1])
+
+    spec = JobSpec.from_dict(
+        {
+            "model": "Qwen/Qwen3.5-0.8B",
+            "algorithm": "grpo",
+            "train": {"batch_size": 4, "epochs": 1, **(train or {})},
+        }
+    )
+    monkeypatch.setattr(_PkgW, "JOB_SPEC", spec, raising=False)
+    monkeypatch.setattr(_PkgW, "SEED", 42, raising=False)
+    monkeypatch.setattr(_PkgW, "THINKING", False, raising=False)
+    monkeypatch.setattr(_PkgW, "require_active_env", lambda: env, raising=False)
+    monkeypatch.setattr(_PkgW, "grpo_overrides", lambda: dict(overrides or {}), raising=False)
+    monkeypatch.setattr(_PkgW, "grpo_mask_truncated_completions", lambda t: False, raising=False)
+    monkeypatch.setattr(_PkgW, "load_tokenizer", lambda *a, **k: _Tokenizer(), raising=False)
+    monkeypatch.setattr(rl_verl, "seed_training_rngs", lambda seed: None)
+    monkeypatch.setattr(rl_verl, "model_max_position_embeddings", lambda *a, **k: 32768)
+    return rl_verl._resolve_single_turn_inputs()
+
+
+def test_capability_guard_rejects_multi_turn_env(monkeypatch):
+    # trl grpo drives multi-turn through a rollout func (rl.py select_grpo_trainer); the verl path
+    # has no equivalent, so it must refuse rather than train only the first turn.
+    with pytest.raises(RuntimeError, match="single-turn, non-tool"):
+        _capability_resolve(monkeypatch, _capability_env(multi_turn=True))
+
+
+def test_capability_guard_rejects_tool_env(monkeypatch):
+    # trl grpo hands tool schemas AND callables to the trainer; verl gets neither, so a tool env
+    # would train against completions that never call a tool.
+    with pytest.raises(RuntimeError, match="single-turn, non-tool"):
+        _capability_resolve(monkeypatch, _capability_env(is_tool_env=True))
+
+
+def test_capability_guard_rejects_image_prompts(monkeypatch):
+    # this guard runs AFTER prompt_messages is built, so it needs a real image content block, not a
+    # flag. trl selects a multimodal trainer here; verl grpo is text-only and would silently drop
+    # the image, training the model on the caption alone.
+    with pytest.raises(RuntimeError, match="non-multimodal grpo only"):
+        _capability_resolve(monkeypatch, _capability_env(images=True))
+
+
+def test_capability_guard_rejects_kl_anchored_warm_start(monkeypatch):
+    # verl computes its kl reference with adapters DISABLED, so under init_from_adapter the
+    # reference is the bare base model and the penalty drags the policy away from the sft start -
+    # the opposite of what the knob asks for. must raise until verl can hold a reference adapter.
+    # the kl coefficient arrives through grpo_overrides, so it must go through the helper: patching
+    # it separately gets clobbered by the helper's own patch and the test then fails on the adapter
+    # download instead, passing a bare raises() while proving nothing about this guard.
+    with pytest.raises(RuntimeError, match="kl_penalty_coef"):
+        _capability_resolve(
+            monkeypatch,
+            _capability_env(),
+            train={"init_from_adapter": "org/some-sft-adapter"},
+            overrides={"kl_penalty_coef": 0.1},
+        )
+
+
+def test_capability_guards_admit_the_supported_single_turn_text_env(monkeypatch):
+    # the control: with none of the four shapes present the resolver must run to completion, so a
+    # guard that fires on every env would fail here instead of passing the four tests above.
+    inp = _capability_resolve(monkeypatch, _capability_env())
+    assert inp["max_prompt_len"] > 0