freesolo-flash-dev 0.2.48__tar.gz → 0.2.49__tar.gz

{freesolo_flash_dev-0.2.48 → freesolo_flash_dev-0.2.49}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freesolo-flash-dev
-Version: 0.2.48
+Version: 0.2.49
 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-0.2.48 → freesolo_flash_dev-0.2.49}/flash/cli/commands.py

@@ -469,7 +469,8 @@ def cmd_env_setup(args) -> int:
             "\n"
             f"{env_comment}"
             "[train]\n"
-            "steps = 150\n"
+            "epochs = 1\n"
+            "max_examples = 2  # rows to train on; the starter dataset has 2 (raise as your dataset grows)\n"
             f"{rl_reasoning_train}"
             "lora_rank = 32\n"
             "# GPU and HF artifacts are managed automatically by the platform: the GPU is\n"
@@ -511,7 +512,8 @@ def cmd_env_setup(args) -> int:
             "[environment]\n"
             'id = ""\n\n'
             "[train]\n"
-            "steps = 100                     # opd is step-driven (like GRPO)\n"
+            "epochs = 1\n"
+            "max_examples = 2  # rows to train on; the starter dataset has 2 (raise as your dataset grows)\n"
             "lora_rank = 32\n"
             "# GPU and HF artifacts are managed automatically by the platform: the GPU is\n"
             "# the cheapest fitting managed class, and artifacts live in a private environment-scoped repo.\n"

{freesolo_flash_dev-0.2.48 → freesolo_flash_dev-0.2.49}/flash/cli/training_doc.py

@@ -103,7 +103,7 @@ id = "your-org/my-env"      # the id printed by `flash env push`
                                    # never stored in the spec
 
 [train]
-epochs = 1                  # SFT is epoch-driven; GRPO is step-driven (steps = N)
+epochs = 1                  # one pass over the retained train rows
 max_examples = 2            # rows to train on (the starter dataset has 2)
 lora_rank = 32
 lora_alpha = 64
@@ -114,7 +114,7 @@ GPU and HF artifacts are **fully managed** — do not pick `gpu.type` or set
 `train.hf_repo`; the allocator picks the cheapest validated managed GPU class that fits,
 and run artifacts are stored in a private environment-scoped repo with content-addressed
 Flash code snapshots. Compose or tweak configs without editing files: `--config
-extra.toml` (deep-merge) and `--set key=value` (e.g. `--set train.steps=300`).
+extra.toml` (deep-merge) and `--set key=value` (e.g. `--set train.epochs=3`).
 
 ### 4. Submit
 
@@ -201,7 +201,7 @@ spending another GPU run:
 | --- | --- | --- |
 | Environment id is blank or stale | `flash train --dry-run` fails, or the worker uses old reward/data | Run `flash env push --name my-env .` after every environment/data edit and paste the returned id into every config you submit. |
 | Local-only env path in config | Config validation says there is no local path mode | Publish first, then use the returned slug in `[environment] id`. `flash train` only runs published env ids, not local paths. |
-| Config knobs are in the wrong table | Validation rejects `[grpo]`, `[sft]`, or unknown `[train]` keys | Put `steps`, `epochs`, `group_size`, `max_completion_tokens`, `temperature`, `max_context_tokens`, LoRA, and other training knobs under `[train]`. |
+| Config knobs are in the wrong table | Validation rejects `[grpo]`, `[sft]`, or unknown `[train]` keys | Put `epochs`, `group_size`, `max_completion_tokens`, `temperature`, `max_context_tokens`, LoRA, and other training knobs under `[train]`. |
 | Trying to pin managed infrastructure | `gpu.type`, `train.hf_repo`, or `model_policy` changes do not do what you expected | Treat GPU choice, model policy, and the run artifact repo as managed. Tune the model, algorithm, environment, and `[train]` knobs instead. |
 | Secrets are not available on the worker | Reward code works locally but remote logs show missing API keys or auth failures | List secret names under `[environment] secrets = [...]`, export those env vars locally before submit, or put them in local `.env` / `.env.local`. Never put secret values in `[worker_env]` or hard-code them in the config. |
 | Wrong model / thinking setting | Config validation fails, or chat behavior does not match the run | Use `flash models`; set `thinking = true` only for supported models. Thinking is a training-time/run-level choice and serving preserves that parity, so `flash chat` does not expose an override flag. |
@@ -214,7 +214,7 @@ spending another GPU run:
 | Final checkpoint regresses | Last step is worse than an earlier checkpoint | Run `flash checkpoints <run-id>`, deploy a specific step with `flash deploy <run-id>/step-N`, and compare with held-out probes before exporting or relying on the final adapter. |
 | Export fails before upload | CLI says no HuggingFace token | Pass `flash export --api-key hf_...`, or set `HF_TOKEN` in your shell, `.env`, or `.env.local`. Exports are private unless you pass `--public`. |
 | SFT loss improves but quality does not | Train loss falls while held-out behavior stalls or degrades | Keep a held-out split outside training. Deploy and score that split; if quality drops, reduce epochs or improve data instead of adding more passes. |
-| Cost surprises | A quick experiment uses more GPU time than intended | Start with `--dry-run` and `--cost`, cap steps/epochs for smoke tests, and scale only after reward/data wiring is proven. Setup time is reported for observability; customer cost is based on training-loop GPU time. |
+| Cost surprises | A quick experiment uses more GPU time than intended | Start with `--dry-run` and `--cost`, keep `epochs` and `max_examples` small for smoke tests, and scale only after reward/data wiring is proven. Setup time is reported for observability; customer cost is based on training-loop GPU time. |
 
 ---
 
@@ -370,7 +370,9 @@ lora_rank = 16     # for VL warm-starts, SFT rank + GRPO rank must fit the effec
 lora_alpha = 32
 ```
 
-SFT is **epoch-driven** (`epochs`); GRPO is **step-driven** (`steps`).
+SFT, GRPO, and OPD all accept **epoch-driven** configs (`epochs`). For GRPO/OPD,
+an epoch is one pass over the retained prompt pool after `max_examples` and prompt-budget filtering;
+optimizer-step counts are derived from those epochs.
 
 ---
 
@@ -379,8 +381,8 @@ SFT is **epoch-driven** (`epochs`); GRPO is **step-driven** (`steps`).
 Pick distillation when a much stronger **teacher** model can grade your student's work
 token-by-token. The student samples on-policy (like GRPO), the managed GLM 5.2 teacher scores
 each of *its own* completions, and a dense per-token loss teaches the student to match the teacher —
-far more sample-efficient than reward-based RL and with no reward to design. It is **step-driven**
-(`steps`) and produces a LoRA served exactly like SFT.
+far more sample-efficient than reward-based RL and with no reward to design. It supports `epochs`
+like SFT/GRPO and produces a LoRA served exactly like SFT.
 
 - **No teacher key or model override to set up.** The GLM 5.2 teacher and its Fireworks key are platform-managed: the
   service supplies its own key to every opd run, so there is nothing to export or declare — an opd
@@ -412,7 +414,8 @@ algorithm = "opd"
 id = "your-org/my-env"
 
 [train]
-steps = 100
+epochs = 1
+max_examples = 2
 lora_rank = 32
 # kl_penalty_coef = 1.0                                 # reverse-KL scale
 ```
@@ -449,7 +452,7 @@ rollouts score somewhere between all-fail and all-pass — is where GRPO has the
 signal.
 
 - If nearly every prompt is solved (most groups score ~1.0): **increase difficulty** —
-  harder prompts, tighter format/reward, more steps.
+  harder prompts, tighter format/reward, more epochs, or more data.
 - If nearly nothing is solved (most groups score ~0.0): **decrease difficulty** —
   easier or few-shot prompts, a more lenient (denser) reward, or warm-start with SFT.
 - In between: good signal — keep iterating at this difficulty.
@@ -500,8 +503,8 @@ on a beyond-noise improvement.
 
 ## Scale the evidence
 
-- **A smoke test is not proof.** A single-digit `steps`, a tiny dataset, or a handful
-  of rollouts only validates the wiring. Scale `steps` / `epochs`, the dataset size,
+- **A smoke test is not proof.** A single-digit derived step count, a tiny dataset, or a handful
+  of rollouts only validates the wiring. Scale `epochs`, the dataset size,
   and `group_size` to the model and the data you actually have before you trust a
   result. Don't cite budget alone as the reason for an underpowered run.
 - **Use the data you have.** Deliberately assign every usable row to training or to a

{freesolo_flash_dev-0.2.48 → freesolo_flash_dev-0.2.49}/flash/cost/spec.py

@@ -10,6 +10,7 @@ import math
 from flash.catalog import samples_on_policy
 from flash.cost.analytical import estimate_cost
 from flash.cost.types import CostEstimate, RunConfig
+from flash.engine.steps import on_policy_steps
 
 
 def _sft_epochs(spec) -> int:
@@ -19,6 +20,14 @@ def _sft_epochs(spec) -> int:
     return int(t.epochs) if t.epochs is not None else RECIPE.sft.num_epochs
 
 
+def _on_policy_epochs(spec) -> int:
+    from flash.engine.recipe import RECIPE
+
+    t = spec.train
+    default = RECIPE.rl.num_epochs if spec.algorithm == "grpo" else RECIPE.opd.num_epochs
+    return int(t.epochs) if t.epochs is not None else default
+
+
 def _sft_seq_len(spec) -> int:
     from flash.engine.recipe import RECIPE
 
@@ -41,6 +50,43 @@ def _sft_example_count(spec) -> int:
     )
 
 
+def _on_policy_example_count(spec) -> int:
+    t = spec.train
+    pinned_examples = int(t.max_examples) if t.max_examples else 0
+    if pinned_examples > 0:
+        return pinned_examples
+    env_examples = _env_max_examples(spec)
+    if env_examples > 0:
+        return env_examples
+    return _on_policy_requested_prompts_per_step(spec)
+
+
+def _env_max_examples(spec) -> int:
+    params = getattr(getattr(spec, "environment", None), "params", {}) or {}
+    if not isinstance(params, dict):
+        return 0
+    try:
+        value = int(params.get("max_examples") or 0)
+    except (TypeError, ValueError):
+        return 0
+    return max(0, value)
+
+
+def _on_policy_requested_prompts_per_step(spec) -> int:
+    from flash.engine.recipe import RECIPE
+
+    t = spec.train
+    default = (
+        RECIPE.rl.prompts_per_step if spec.algorithm == "grpo" else RECIPE.opd.prompts_per_step
+    )
+    return max(1, int(t.batch_size) if t.batch_size is not None else default)
+
+
+def _on_policy_prompts_per_step(spec, examples: int) -> int:
+    requested = _on_policy_requested_prompts_per_step(spec)
+    return max(1, min(requested, max(1, int(examples))))
+
+
 def _sft_realized_batch(spec) -> int:
     from flash.catalog import vocab_size_for
     from flash.engine.recipe import RECIPE
@@ -68,22 +114,26 @@ def _sft_steps_from_examples(spec, examples: int, *, apply_cap: bool) -> int:
 
 
 def spec_steps(spec) -> int:
-    """Per-seed optimizer steps implied by a train spec (mirrors the worker). GRPO: ``train.steps``
-    (else recipe default). SFT: ``epochs x ceil(num_examples / realized_batch)`` capped by
-    ``max_steps``, where ``num_examples`` must be pinned by ``max_examples``."""
-    from flash.engine.recipe import RECIPE
+    """Per-seed optimizer steps implied by a train spec (mirrors the worker).
 
-    t = spec.train
+    SFT: ``epochs x ceil(num_examples / realized_batch)`` capped by ``max_steps``. GRPO/OPD:
+    ``epochs`` means passes over ``max_examples`` rows when pinned, otherwise the estimate uses one
+    prompt batch per epoch.
+    """
     if spec.algorithm == "grpo":
-        if t.steps is not None:
-            return max(1, int(t.steps))
-        return RECIPE.rl.num_steps
+        examples = _on_policy_example_count(spec)
+        return on_policy_steps(
+            epochs=_on_policy_epochs(spec),
+            prompt_count=examples,
+            prompts_per_step=_on_policy_prompts_per_step(spec, examples),
+        )
     if spec.algorithm == "opd":
-        # Step-driven like GRPO (on-policy sampling), NOT example-driven — so a opd quote never
-        # demands [train].max_examples (the SFT fallback below would raise).
-        if t.steps is not None:
-            return max(1, int(t.steps))
-        return RECIPE.opd.num_steps
+        examples = _on_policy_example_count(spec)
+        return on_policy_steps(
+            epochs=_on_policy_epochs(spec),
+            prompt_count=examples,
+            prompts_per_step=_on_policy_prompts_per_step(spec, examples),
+        )
     # max_examples is a CAP; 0 (like None) means "no cap" (worker trains the full dataset), so
     # don't let max_examples=0 price a single step.
     return _sft_steps_from_examples(spec, _sft_example_count(spec), apply_cap=True)

{freesolo_flash_dev-0.2.48 → freesolo_flash_dev-0.2.49}/flash/engine/recipe.py

@@ -40,7 +40,7 @@ class RLConfig:
     max_completion_len_thinking: int = 1536
     prompts_per_step: int = 64
     group_size: int = 8
-    num_steps: int = 150
+    num_epochs: int = 1
     sampling_temperature: float = 1.0
     sampling_top_p: float = 1.0
 
@@ -54,8 +54,6 @@ class OPDConfig:
     # platform-managed and intentionally not configurable from [train].
     teacher_model: str = "accounts/fireworks/models/glm-5p2"
     teacher_base_url: str = "https://api.fireworks.ai/inference/v1"
-    # OPD is step-driven like GRPO (on-policy sampling), not epoch-driven like SFT.
-    num_steps: int = 100
     learning_rate: float = 1e-5
     max_prompt_len: int = 1024
     max_completion_len: int = 512
@@ -65,6 +63,7 @@ class OPDConfig:
     # Student samples per prompt. 1 is enough for a direct KD loss (no group-relative baseline
     # as in GRPO); raise for more teacher-scored coverage per prompt at higher cost.
     group_size: int = 1
+    num_epochs: int = 1
     sampling_temperature: float = 1.0
     sampling_top_p: float = 1.0
     # Reverse-KL coefficient for the groupwise reverse-KL loss; scales the per-span

freesolo_flash_dev-0.2.49/flash/engine/steps.py

@@ -0,0 +1,18 @@
+"""Training-step derivation shared by worker and cost-estimate paths."""
+
+from __future__ import annotations
+
+import math
+
+
+def on_policy_steps(
+    *,
+    epochs: int,
+    prompt_count: int,
+    prompts_per_step: int,
+) -> int:
+    """Resolve GRPO/OPD optimizer steps from full passes over the retained prompt pool."""
+    prompt_count = int(prompt_count)
+    if prompt_count <= 0:
+        raise ValueError("cannot derive epoch-based steps without at least one retained prompt")
+    return max(1, math.ceil(prompt_count * int(epochs) / max(1, int(prompts_per_step))))

{freesolo_flash_dev-0.2.48 → freesolo_flash_dev-0.2.49}/flash/engine/worker/opd.py

@@ -29,6 +29,7 @@ from dataclasses import dataclass
 
 from flash.engine.chalk_kernels import active_kernels, install_chalk_kernels
 from flash.engine.recipe import RECIPE
+from flash.engine.steps import on_policy_steps
 from flash.engine.vram import opd_completion_len
 from flash.engine.worker._pkg import W as _w
 from flash.engine.worker.heartbeat import liveness_heartbeat
@@ -75,7 +76,7 @@ class OpdKnobs:
 
     teacher_model: str = ""
     teacher_base_url: str = ""
-    steps: int = 0
+    epochs: int = RECIPE.opd.num_epochs
     learning_rate: float = 0.0
     temperature: float = 0.0
     top_p: float = 1.0
@@ -116,7 +117,7 @@ def _resolve_opd_knobs() -> OpdKnobs:
     return OpdKnobs(
         teacher_model=d.teacher_model,
         teacher_base_url=d.teacher_base_url,
-        steps=int(opt("steps", 0) or d.num_steps),
+        epochs=int(t.epochs) if t and t.epochs is not None else d.num_epochs,
         learning_rate=float(opt("learning_rate", 0) or d.learning_rate),
         temperature=float(
             opt("temperature", None)
@@ -263,7 +264,7 @@ def run_opd():
     warm_start = _w.JOB_SPEC.train.init_from_adapter if _w.JOB_SPEC else ""
     print(
         f"[opd] gkd (groupwise reverse-KL) teacher={knobs.teacher_model} "
-        f"steps={knobs.steps} warm_start={warm_start or 'none'} "
+        f"epochs={knobs.epochs} warm_start={warm_start or 'none'} "
         f"mode={'multi-turn' if multi_turn else 'single-turn'}"
     )
 
@@ -309,9 +310,12 @@ def run_opd():
             "opd: the environment dataset is empty — no prompts to sample on-policy. Check the "
             "environment's dataset()/train split before provisioning a GPU."
         )
+    _max_examples = getattr(_w.JOB_SPEC.train, "max_examples", None) if _w.JOB_SPEC else None
+    max_examples = int(_max_examples or 0) if _max_examples is not None else 0
+    if max_examples > 0:
+        train = train[:max_examples]
     rng = random.Random(_w.SEED)
     rng.shuffle(train)
-    steps = knobs.steps
     ppl_step = knobs.prompts_per_step
     group = knobs.group_size
     # Prompt budget mirrors GRPO: DROP (not truncate) prompts over the context budget, so the student
@@ -375,6 +379,21 @@ def run_opd():
             f"[opd] filtered {n_over_budget}/{len(train)} prompts over the "
             f"{prompt_budget}-token budget; pool = {len(examples)}"
         )
+    if ppl_step > len(examples):
+        print(
+            f"[opd] lowering prompts_per_step from {ppl_step} to {len(examples)}: "
+            "only that many prompt(s) fit after filtering"
+        )
+        ppl_step = len(examples)
+    steps = on_policy_steps(
+        epochs=knobs.epochs,
+        prompt_count=len(examples),
+        prompts_per_step=ppl_step,
+    )
+    print(
+        f"[opd] epochs={knobs.epochs} over {len(examples)} retained prompt(s) at "
+        f"{ppl_step} prompts/step -> steps={steps}"
+    )
 
     # Now that a non-empty on-policy pool is confirmed, prefetch the full base weights (deferred from
     # setup so an all-over-budget dataset fails before this download). Still inside the setup phase
@@ -573,9 +592,12 @@ def run_opd():
     # but opd only set attn_implementation at LOAD, so both the on-policy generate and the gkd loss
     # forward ran under the default SDPA dispatch and silently lost the cuDNN kernel (codex[bot]).
     # No-op (nullcontext) on non-Blackwell GPUs / when _attn isn't "sdpa".
+    def _samples_progress():
+        return samples_seen
+
     with (
         liveness_heartbeat(
-            "opd_step", progress=lambda: samples_seen, fields=lambda: {"step": opt_steps}
+            "opd_step", progress=_samples_progress, fields=lambda: {"step": opt_steps}
         ),
         _sdpa_cudnn_ctx(_attn),
     ):
@@ -633,6 +655,7 @@ def run_opd():
                         prompts.append(prompt_ids)
                 with liveness_heartbeat(
                     "opd_step",
+                    progress=_samples_progress,
                     fields=lambda _step=opt_steps: {"step": _step},
                     keepalive=True,
                 ):
@@ -804,6 +827,8 @@ def run_opd():
         generated_tokens=generated_tokens,
         notes={
             "steps": steps,
+            "epochs": knobs.epochs,
+            "retained_prompts": len(examples),
             # Optimizer steps actually applied; < steps if any iteration had no usable teacher
             # signal (skipped). loss_curve length == opt_steps, so reporting stays honest.
             "opt_steps": opt_steps,
@@ -976,8 +1001,11 @@ def _generate_one(*, model, tok, device, prompt_tensor, gen_cfg, knobs) -> _GenR
 def _gen_from_vllm_output(out: OpdVllmOutput, tok, knobs) -> _GenResult:
     """Apply OPD's pre-scoring gates to one vLLM completion."""
     completion_ids = [int(t) for t in out.token_ids]
-    completion_text = out.text or tok.decode(completion_ids, skip_special_tokens=True)
-    stop_text = tok.decode(completion_ids, skip_special_tokens=False)
+    decode = getattr(tok, "decode", None)
+    completion_text = out.text or (
+        decode(completion_ids, skip_special_tokens=True) if decode else ""
+    )
+    stop_text = decode(completion_ids, skip_special_tokens=False) if decode else completion_text
     if not (
         out.terminated
         or _rollout_terminated(

{freesolo_flash_dev-0.2.48 → freesolo_flash_dev-0.2.49}/flash/engine/worker/rl.py

@@ -8,6 +8,7 @@ import time
 
 from flash.engine.chalk_kernels import active_kernels, install_chalk_kernels
 from flash.engine.recipe import RECIPE
+from flash.engine.steps import on_policy_steps
 from flash.engine.worker._pkg import W as _w
 from flash.engine.worker.grpo import resolve_grpo_sleep_mode
 from flash.engine.worker.heartbeat import liveness_heartbeat
@@ -54,11 +55,8 @@ def run_rl():
     model_id = _w.JOB_SPEC.model if _w.JOB_SPEC else RECIPE.hf_model_id
     download_seconds = _w.prefetch_model(model_id)
     rl = RECIPE.rl
-    steps = int(
-        _w.JOB_SPEC.train.steps if _w.JOB_SPEC and _w.JOB_SPEC.train.steps is not None else rl.num_steps
-    )
-    gcfg = _w.grpo_overrides()
     _t = _w.JOB_SPEC.train if _w.JOB_SPEC else None
+    gcfg = _w.grpo_overrides()
     prompts_per_step = int(
         _t.batch_size if _t and _t.batch_size is not None else rl.prompts_per_step
     )
@@ -91,6 +89,10 @@ def run_rl():
             tok.pad_token = tok.eos_token
 
         train = env.dataset()
+        _max_examples = getattr(_t, "max_examples", None) if _t else None
+        max_examples = int(_max_examples or 0) if _max_examples is not None else 0
+        if max_examples > 0:
+            train = train[:max_examples]
         rng = random.Random(_w.SEED)
         rng.shuffle(train)
         if conversational:
@@ -320,6 +322,16 @@ def run_rl():
         print(
             "WARN: generation batch not divisible by group size; check prompts_per_step/group_size"
         )
+    epochs = int(_t.epochs) if _t and _t.epochs is not None else RECIPE.rl.num_epochs
+    steps = on_policy_steps(
+        epochs=epochs,
+        prompt_count=len(prompts),
+        prompts_per_step=batching["unique_prompts_per_step"],
+    )
+    print(
+        f"[rl] epochs={epochs} over {len(prompts)} retained prompt(s) at "
+        f"{batching['unique_prompts_per_step']} unique_prompts/step -> steps={steps}"
+    )
     print(
         f"[rl] GRPO batching: per_device={batching['per_device_train_batch_size']} "
         f"grad_accum={batching['gradient_accumulation_steps']} "
@@ -692,6 +704,8 @@ def run_rl():
         generated_tokens=gen_tokens,
         notes={
             "steps": steps,
+            "epochs": epochs,
+            "retained_prompts": len(prompts),
             "resumed": bool(resume_ckpt),
             "download_seconds": download_seconds,
             "hf_transfer": os.environ.get("HF_HUB_ENABLE_HF_TRANSFER", ""),

{freesolo_flash_dev-0.2.48 → freesolo_flash_dev-0.2.49}/flash/providers/_worker.py

@@ -235,10 +235,6 @@ def build_worker_env(
     env["HF_REPO"] = spec.train.hf_repo
     if getattr(spec.gpu, "network_volume", None):
         env.update(weight_cache_env())
-    if spec.train.steps is not None:
-        env["RL_STEPS"] = str(spec.train.steps)
-    if spec.train.epochs is not None:
-        env["SFT_EPOCHS"] = str(spec.train.epochs)
     for k in (
         "SFT_PER_DEVICE_BS",
         "VLLM_USE_V1",

{freesolo_flash_dev-0.2.48 → freesolo_flash_dev-0.2.49}/flash/schema/__init__.py

@@ -190,7 +190,6 @@ _TOP_LEVEL_KEYS = frozenset(
 )
 _TRAIN_KEYS = frozenset(
     {
-        "steps",
         "epochs",
         "lora_rank",
         "lora_alpha",
@@ -333,7 +332,6 @@ def spec_from_dict(raw: dict[str, Any], run_id: str | None = None) -> JobSpec:
             secrets=environment_secrets,
         ),
         train=TrainSpec(
-            steps=_train_int(train_raw, "steps", minimum=1),
             epochs=_train_int(train_raw, "epochs", minimum=1),
             lora_rank=lora_rank,
             lora_alpha=_train_int(train_raw, "lora_alpha", minimum=1) or 64,
@@ -379,9 +377,7 @@ def _validate_sft(spec: JobSpec) -> None:
 
 
 def _validate_grpo(spec: JobSpec) -> None:
-    """GRPO contract: step-driven, so steps (when pinned) must be positive."""
-    if spec.train.steps is not None and spec.train.steps <= 0:
-        raise ConfigError("train.steps must be positive for GRPO")
+    """GRPO contract: epochs derive passes over retained prompts."""
     if spec.train.group_size is not None and spec.train.group_size < 2:
         raise ConfigError(
             "train.group_size must be >= 2 for GRPO (TRL needs at least two generations "
@@ -390,13 +386,10 @@ def _validate_grpo(spec: JobSpec) -> None:
 
 
 def _validate_opd(spec: JobSpec) -> None:
-    """OPD contract: step-driven (positive steps) with a usable prompt budget.
+    """OPD contract: epochs derive passes over retained prompts.
 
     The teacher key (FIREWORKS_API_KEY) is a platform-owned credential the control plane injects into
     the worker env (build_worker_env), like HF_TOKEN — never a user-declared secret."""
-    if spec.train.steps is not None and spec.train.steps <= 0:
-        # OPD is step-driven (on-policy sampling), like GRPO — not epoch-driven.
-        raise ConfigError("train.steps must be positive for opd")
     if spec.train.max_context_tokens:
         # Mirror run_opd's prompt-budget guard at PARSE time: a context budget that leaves no room
         # for any prompt after the completion budget is rejected here, BEFORE a paid worker is

{freesolo_flash_dev-0.2.48 → freesolo_flash_dev-0.2.49}/flash/spec.py

@@ -101,7 +101,6 @@ FIXED_SEED = 42
 
 @dataclass(frozen=True)
 class TrainSpec:
-    steps: int | None = None
     epochs: int | None = None
     lora_rank: int = 32
     lora_alpha: int = 64
@@ -191,7 +190,6 @@ class JobSpec:
                 resolved_sha=str(env.get("resolved_sha") or ""),
             ),
             train=TrainSpec(
-                steps=_opt_int(train.get("steps")),
                 epochs=_opt_int(train.get("epochs")),
                 lora_rank=int(train.get("lora_rank", 32)),
                 lora_alpha=int(train.get("lora_alpha", 64)),

{freesolo_flash_dev-0.2.48 → freesolo_flash_dev-0.2.49}/pyproject.toml

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

{freesolo_flash_dev-0.2.48 → freesolo_flash_dev-0.2.49}/tests/test_agent_flash_cli_contract.py

@@ -99,7 +99,8 @@ def test_train_dry_run_emits_run_id_and_state(tmp_path: Path, capsys) -> None:
         'id = "owner/env"\n'
         "[train]\n"
         'hf_repo = "owner/runs"\n'
-        "steps = 10\n"
+        "epochs = 1\n"
+        "max_examples = 10\n"
         "[gpu]\n"
         'type = "RTX 5090"\n'
     )

{freesolo_flash_dev-0.2.48 → freesolo_flash_dev-0.2.49}/tests/test_algorithms.py

@@ -23,7 +23,7 @@ def test_opd_algorithm_accepted():
             "model": "Qwen/Qwen3.5-4B",
             "algorithm": "opd",
             "environment": {"id": "github:owner/repo@main:env/environment.py"},
-            "train": {"steps": 10, "hf_repo": "owner/runs"},
+            "train": {"epochs": 1, "max_examples": 10, "hf_repo": "owner/runs"},
         },
         run_id="x",
     )
@@ -55,7 +55,7 @@ def test_opd_capability_gated_per_model():
                     "model": "test/no-opd",
                     "algorithm": "opd",
                     "environment": {"id": "github:owner/repo@main:env/environment.py"},
-                    "train": {"steps": 1, "hf_repo": "owner/runs"},
+                    "train": {"epochs": 1, "max_examples": 1, "hf_repo": "owner/runs"},
                 },
                 run_id="x",
             )
@@ -84,7 +84,7 @@ def test_grpo_capability_still_enforced():
                     "model": "test/sft-only",
                     "algorithm": "grpo",
                     "environment": {"id": "github:owner/repo@main:env/environment.py"},
-                    "train": {"steps": 1, "hf_repo": "owner/runs"},
+                    "train": {"epochs": 1, "max_examples": 1, "hf_repo": "owner/runs"},
                 },
                 run_id="x",
             )
@@ -110,7 +110,7 @@ def test_qwen35_9b_now_supports_grpo():
             "model": "Qwen/Qwen3.5-9B",
             "algorithm": "grpo",
             "environment": {"id": "github:owner/repo@main:env/environment.py"},
-            "train": {"steps": 1, "hf_repo": "owner/runs"},
+            "train": {"epochs": 1, "max_examples": 1, "hf_repo": "owner/runs"},
             "gpu": {"type": "A100 PCIe"},
         },
         run_id="x",

{freesolo_flash_dev-0.2.48 → freesolo_flash_dev-0.2.49}/tests/test_allocator.py

@@ -394,7 +394,7 @@ def test_observed_qwen2_opd_vllm_case_routes_off_32gb_cards(monkeypatch):
     from flash.providers.base import get_gpu_info, provisional_gpu
 
     monkeypatch.setattr(allocator, "available_providers", lambda: ("runpod",))
-    train = {"steps": 60, "max_completion_tokens": 128, "lora_rank": 32, "lora_alpha": 64}
+    train = {"epochs": 1, "max_completion_tokens": 128, "lora_rank": 32, "lora_alpha": 64}
 
     need = required_vram_gb("Qwen/Qwen3.5-2B", "opd", train=train)
     assert need > 40
@@ -433,7 +433,7 @@ def test_observed_qwen4b_opd_vllm_startup_case_routes_off_40gb_cards(monkeypatch
 
     monkeypatch.setattr(allocator, "available_providers", lambda: ("runpod",))
     train = {
-        "steps": 1,
+        "epochs": 1,
         "max_context_tokens": 8192,
         "max_completion_tokens": 128,
         "lora_rank": 32,
@@ -488,14 +488,14 @@ def test_opd_catalog_model_config_gpu_matrix_routes_to_fitting_cards(monkeypatch
     configs = {
         # Matches the failed continuation shape from the OPD/vLLM RTX 5090 report.
         "observed_2b_128tok_r32": {
-            "steps": 1,
+            "epochs": 1,
             "max_completion_tokens": 128,
             "lora_rank": 32,
             "lora_alpha": 64,
         },
-        "recipe_default": {"steps": 1},
+        "recipe_default": {"epochs": 1},
         "opd_prompt_batch": {
-            "steps": 1,
+            "epochs": 1,
             "batch_size": 8,
             "group_size": 1,
             "max_context_tokens": 1536,
@@ -503,7 +503,7 @@ def test_opd_catalog_model_config_gpu_matrix_routes_to_fitting_cards(monkeypatch
             "lora_rank": 16,
         },
         "longer_context": {
-            "steps": 1,
+            "epochs": 1,
             "batch_size": 8,
             "group_size": 1,
             "max_context_tokens": 4096,
@@ -511,7 +511,7 @@ def test_opd_catalog_model_config_gpu_matrix_routes_to_fitting_cards(monkeypatch
             "lora_rank": 16,
         },
         "longer_completion": {
-            "steps": 1,
+            "epochs": 1,
             "batch_size": 1,
             "group_size": 1,
             "max_context_tokens": 4096,
@@ -519,7 +519,7 @@ def test_opd_catalog_model_config_gpu_matrix_routes_to_fitting_cards(monkeypatch
             "lora_rank": 16,
         },
         "wide_rollout_batch": {
-            "steps": 1,
+            "epochs": 1,
             "batch_size": 8,
             "group_size": 4,
             "max_context_tokens": 4096,
@@ -538,7 +538,7 @@ def test_opd_catalog_model_config_gpu_matrix_routes_to_fitting_cards(monkeypatch
             rc = RunConfig(
                 model_id,
                 "opd",
-                int(train.get("steps", 1)),
+                int(train.get("epochs", 1)),
                 seq_len=train.get("max_context_tokens"),
                 completion_len=train.get("max_completion_tokens"),
                 batch_size=train.get("batch_size"),
@@ -675,7 +675,7 @@ def test_catalog_model_algorithm_config_gpu_matrix_resolves_to_fitting_cards(mon
         for algo in ALGORITHMS:
             if algo not in info.algos:
                 continue
-            train = {"epochs": 1, "max_examples": 8} if algo == "sft" else {"steps": 1}
+            train = {"epochs": 1, "max_examples": 8}
             need = allocator.required_vram_gb(model_id, algo, train=train, thinking=False)
             expected_gpu = provisional_gpu(model_id, algo, train=train, thinking=False)