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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freesolo-flash-dev
-Version: 0.2.48
+Version: 0.2.50
 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.50}/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.50}/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.50}/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.50}/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.50/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.50}/flash/engine/worker/grpo.py

@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-import os
-
 from flash.engine.worker._pkg import W as _w
 
 
@@ -86,17 +84,6 @@ def rl_per_device_comps(
     """
     default = 2 if _w.THINKING else 8
 
-    _ovr = os.environ.get("FLASH_RL_PER_DEVICE_COMPS", "").strip()
-    if _ovr:
-        try:
-            forced = int(_ovr)
-            if forced >= 1:
-                print(f"rl_per_device_comps: FLASH_RL_PER_DEVICE_COMPS override -> per_device={forced}")
-                return forced
-            print(f"rl_per_device_comps: ignoring non-positive FLASH_RL_PER_DEVICE_COMPS={_ovr!r}")
-        except ValueError:
-            print(f"rl_per_device_comps: ignoring non-integer FLASH_RL_PER_DEVICE_COMPS={_ovr!r}")
-
     logits_cap = _RL_PER_DEVICE_MAX
     if completion_len > 0 and not fused_logits:
         logits_cap = max(1, int(6.0e9 / (max(1, completion_len) * vocab * 4)))