freesolo-flash-dev 1.0.0__tar.gz → 1.0.2__tar.gz

{freesolo_flash_dev-1.0.0 → freesolo_flash_dev-1.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: freesolo-flash-dev
-Version: 1.0.0
+Version: 1.0.2
 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.0 → freesolo_flash_dev-1.0.2}/flash/catalog.py

@@ -111,6 +111,8 @@ class ModelInfo:
     # multimodal-nested config, so the curated values are what actually engage the gate.
     num_layers: int = 0
     hidden_size: int = 0
+    # vllm hybrid-mamba cache block size in tokens. 0 means the model has no catalogued mamba floor.
+    mamba_block_size: int = 0
 
     @property
     def is_moe(self) -> bool:
@@ -124,6 +126,8 @@ class ModelInfo:
 
     def to_dict(self) -> dict[str, Any]:
         data = asdict(self)
+        if not data["mamba_block_size"]:
+            del data["mamba_block_size"]
         serving = data["serving"]
         if serving is None:
             del data["serving"]
@@ -170,7 +174,7 @@ MODELS: dict[str, ModelInfo] = {
             serve_model_id=SERVING_FP8_MODEL_REPOS["openbmb/MiniCPM5-1B"],
             max_loras=16,
             max_lora_rank=128,
-            max_model_len=8192,
+            max_model_len=32768,
         ),
         thinking="hybrid",
         notes="On-device class SLM (131k ctx); standard Llama architecture.",
@@ -189,7 +193,7 @@ MODELS: dict[str, ModelInfo] = {
             serve_model_id=SERVING_FP8_MODEL_REPOS["Qwen/Qwen3.5-0.8B"],
             max_loras=16,
             max_lora_rank=128,
-            max_model_len=8192,
+            max_model_len=32768,
         ),
         thinking="hybrid",
         notes="Smallest Qwen3.5; cheap smoke/dev runs with the modern arch.",
@@ -208,7 +212,7 @@ MODELS: dict[str, ModelInfo] = {
             serve_model_id=SERVING_FP8_MODEL_REPOS["Qwen/Qwen3.5-2B"],
             max_loras=16,
             max_lora_rank=128,
-            max_model_len=8192,
+            max_model_len=32768,
         ),
         thinking="hybrid",
     ),
@@ -226,7 +230,7 @@ MODELS: dict[str, ModelInfo] = {
             serve_model_id=SERVING_FP8_MODEL_REPOS["Qwen/Qwen3.5-4B"],
             max_loras=16,
             max_lora_rank=64,
-            max_model_len=8192,
+            max_model_len=32768,
             max_num_seqs=8,
             gpu_memory_utilization=0.98,
         ),
@@ -247,11 +251,11 @@ MODELS: dict[str, ModelInfo] = {
         quant="bf16",
         recommended_gpu="A100 PCIe",
         serving=ServingCapacity(
-            gpu="L4",
+            gpu="H100",
             serve_model_id=SERVING_FP8_MODEL_REPOS["Qwen/Qwen3.5-9B"],
             max_loras=16,
             max_lora_rank=64,
-            max_model_len=8192,
+            max_model_len=32768,
             max_num_seqs=8,
             gpu_memory_utilization=0.98,
         ),
@@ -271,6 +275,10 @@ MODELS: dict[str, ModelInfo] = {
         # layers x 2048 hidden (hybrid GatedDeltaNet + full-attention, 256 experts / 8 active).
         num_layers=40,
         hidden_size=2048,
+        # vllm 0.19.1 model_executor/models/config.py derives this from the qwen config via
+        # mamba_utils.py: the 1,097,728-byte gdn state page needs 1072 fp8 attention tokens
+        # after the 16-token backend alignment applied by hybridattentionmambamodelconfig.
+        mamba_block_size=1072,
         vocab_size=248_320,
         algos=ALGORITHMS,
         min_vram_gb=141,
@@ -312,6 +320,17 @@ MODELS: dict[str, ModelInfo] = {
 }
 
 
+def opd_mamba_batched_token_floor(
+    model_id: str, seq_cap: int, max_num_seqs: int | None
+) -> int | None:
+    """return a mamba floor only when vllm's derived opd scheduler budget is too small."""
+    info = MODELS.get(model_id)
+    if info is None or info.mamba_block_size <= 0 or max_num_seqs is None:
+        return None
+    derived_budget = int(max_num_seqs) * int(seq_cap)
+    return info.mamba_block_size if derived_budget < info.mamba_block_size else None
+
+
 def list_models() -> list[ModelInfo]:
     return sorted(MODELS.values(), key=lambda m: (m.min_vram_gb, m.id))
 

{freesolo_flash_dev-1.0.0 → freesolo_flash_dev-1.0.2}/flash/cli/commands.py

@@ -214,6 +214,7 @@ def _cmd_train_cost(args) -> int:
     Catalog-only and deterministic. SFT cost never imports the environment; it requires a positive
     [train].max_examples row count instead of guessing or locally counting a dataset."""
     from flash.cost import estimate_cost
+    from flash.lora_rank import preflight_train_context_within_serving
 
     spec = spec_from_file(
         args.config,
@@ -221,6 +222,7 @@ def _cmd_train_cost(args) -> int:
         overrides=args.overrides,
         extra_configs=args.extra_configs,
     )
+    preflight_train_context_within_serving(spec)
     if spec.train.init_from_adapter:
         # --cost is offline/catalog-only and cannot read the source adapter, so the rank stays at the
         # local default. Warm starts train and are priced at the SOURCE adapter's authoritative rank
@@ -302,23 +304,24 @@ def cmd_train(args) -> int:
     )
     payload = spec_payload(spec, authored_train_keys=authored_train_keys)
     client = client_from_config()
+    client_train_schema = {
+        "version": __version__,
+        "fields": train_schema_metadata(),
+        "authored_keys": sorted(authored_train_keys),
+    }
+    runtime_secrets = (
+        runtime_secrets_from_local_env(args.config, keys=spec.environment.secrets) or None
+    )
     if args.dry_run:
-        # Dry-run is a faithful server-side preview: the control plane runs the SAME config
-        # validation and warm-start/serving preflights it would at real submit (serving rank/context
-        # caps, the continued warm-start rank match, cost quote) and records a state=dry_run run, but
-        # allocates no GPU and charges nothing. Local runtime secrets aren't sent — the server
-        # relaxes the required-[environment].secrets check for a preview, so `--dry-run` works before
-        # prod secrets are wired up. A rejection surfaces as the server's `error: ...` (exit 1),
-        # exactly as a real submit would.
+        # dry-run is a faithful server-side preview: it sends the same declared secrets and runs the
+        # same config, warm-start, serving, and cost preflights as a real submit, but allocates no gpu
+        # and charges nothing. a rejection surfaces as the server's error with exit status 1.
         try:
             status = client.create_run(
                 payload,
+                runtime_secrets=runtime_secrets,
                 dry_run=True,
-                client_train_schema={
-                    "version": __version__,
-                    "fields": train_schema_metadata(),
-                    "authored_keys": sorted(authored_train_keys),
-                },
+                client_train_schema=client_train_schema,
             )
         except ApiError as exc:
             detail = _legacy_train_key_rejection_detail(exc, authored_train_keys)
@@ -338,7 +341,8 @@ def cmd_train(args) -> int:
         return 0
     status = client.create_run(
         payload,
-        runtime_secrets=runtime_secrets_from_local_env(args.config, keys=spec.environment.secrets),
+        runtime_secrets=runtime_secrets,
+        client_train_schema=client_train_schema,
     )
     run_id = status["run_id"]
     logger.info(

{freesolo_flash_dev-1.0.0 → freesolo_flash_dev-1.0.2}/flash/cli/training_doc.py

@@ -154,6 +154,47 @@ flash undeploy <run-id>          # tear the endpoint down
 flash export --adapter-id <run-id> --repository <you>/<repo>  # copy adapter weights to your HF repo
 ```
 
+### Loading an exported adapter locally (transformers + peft)
+
+Flash trains the Qwen3.5/3.6 family against the full multimodal module tree, so adapter
+weights saved by the worker carry a `language_model.` infix in their tensor keys
+(`base_model.model.model.language_model.layers.*`). During `flash export`, adapters that
+can be represented in the text-only namespace are normalized to
+`base_model.model.model.layers.*`. When an export retains non-LM tensors, it keeps the
+multimodal namespace instead. Do not infer the namespace solely from whether `flash export`
+was used: inspect the keys. For normalized keys, load with vanilla peft and
+`AutoModelForCausalLM`:
+
+```python
+from peft import PeftModel
+from transformers import AutoModelForCausalLM
+
+base = AutoModelForCausalLM.from_pretrained("Qwen/Qwen3.5-0.8B")  # qwen3.5 causal-lm class
+model = PeftModel.from_pretrained(base, "<you>/<repo>")
+```
+
+**Before you trust any local eval, check the key namespace matches the model class you
+loaded.** peft does NOT error on mismatched keys — it emits a `UserWarning` about missing
+adapter keys and silently applies *nothing*, so you would benchmark the bare base model
+believing it is your adapter. If the inspected keys carry the `language_model.` infix,
+load the base with the multimodal class whose parameters live under that namespace instead:
+
+```python
+# infixed keys (base_model.model.model.language_model.layers.*) need the multimodal class:
+from transformers import AutoModelForImageTextToText
+
+base = AutoModelForImageTextToText.from_pretrained("Qwen/Qwen3.5-0.8B")
+# qwen3.5/3.6 dense models resolve to Qwen3_5ForConditionalGeneration
+# qwen3.6-35b-a3b (moe) resolves to Qwen3_5MoeForConditionalGeneration
+model = PeftModel.from_pretrained(base, "<you>/<repo>")
+```
+
+To check which form you have, read the safetensors key names (stdlib, no torch needed):
+the JSON header of `adapter_model.safetensors` lists every tensor key. Rule of thumb:
+`model.layers.*` keys pair with `AutoModelForCausalLM`; `model.language_model.layers.*`
+keys pair with the `*ForConditionalGeneration` class. After loading, confirm the adapter
+actually applied: outputs (or a probe metric) must differ from the bare base model.
+
 The rest of this file is about doing the above *well* — designing a reward that teaches,
 and deciding honestly whether a run improved.
 
@@ -221,6 +262,7 @@ spending another GPU run:
 | Run looks stuck after disconnecting | Terminal stopped streaming but the job may still be alive | Ctrl-C detaches. Use `flash log <run-id> --follow` to reattach, `flash log <run-id>` for the console/error output, or `flash cancel <run-id>` if you intentionally want to stop it. |
 | 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`. |
+| Exported adapter is a silent no-op locally | peft warns about missing adapter keys and local eval matches the bare base model | The adapter's key namespace does not match the loaded model class. `model.layers.*` keys pair with `AutoModelForCausalLM`; `model.language_model.layers.*` keys pair with `Qwen3_5ForConditionalGeneration` / `Qwen3_5MoeForConditionalGeneration` (via `AutoModelForImageTextToText`). See "Loading an exported adapter locally". |
 | 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`, 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. |
 

{freesolo_flash_dev-1.0.0 → freesolo_flash_dev-1.0.2}/flash/client/http.py

@@ -343,8 +343,8 @@ class ApiClient:
             # Server-side preview: runs the same validation/preflights as a real submit and records a
             # state=dry_run run, but allocates no GPU and charges nothing. Returns that status.
             body["dry_run"] = True
-            if client_train_schema is not None:
-                body["client_train_schema"] = client_train_schema
+        if client_train_schema is not None:
+            body["client_train_schema"] = client_train_schema
         return self._request("POST", "/v1/runs", body=body)
 
     def list_runs(self) -> list[dict]:

{freesolo_flash_dev-1.0.0 → freesolo_flash_dev-1.0.2}/flash/engine/worker/opd_vllm.py

@@ -127,7 +127,8 @@ def opd_vllm_kwargs(model_id: str, knobs: Any, seq_cap: int) -> dict[str, Any]:
 
     fp8_kv = bool(cc >= (8, 9))
     kwargs["kv_cache_dtype"] = "fp8" if fp8_kv else None
-    kwargs["max_num_batched_tokens"] = max(8192, int(seq_cap)) if card_gb >= 140 else None
+    if card_gb >= 140:
+        kwargs["max_num_batched_tokens"] = max(8192, int(seq_cap))
 
     if card_gb > 0:
         try:
@@ -189,6 +190,12 @@ def opd_vllm_kwargs(model_id: str, knobs: Any, seq_cap: int) -> dict[str, Any]:
             kwargs["rollout_batch_size"] = rollout_concurrency
         except Exception as exc:
             print(f"[opd] vLLM memory-util sizing failed; using 0.10: {exc}")
+    if card_gb < 140:
+        from flash.catalog import opd_mamba_batched_token_floor
+
+        kwargs["max_num_batched_tokens"] = opd_mamba_batched_token_floor(
+            model_id, seq_cap, kwargs["max_num_seqs"]
+        )
     if startup_oom is not None:
         raise startup_oom
 

{freesolo_flash_dev-1.0.0 → freesolo_flash_dev-1.0.2}/flash/runner/__init__.py

@@ -691,7 +691,7 @@ def _prepare_init_from_adapter(
     owner_key_id: int | None = None,
     token: str | None = None,
 ) -> tuple[JobSpec, JobSpec, dict | None]:
-    """Preserve the public request while applying source metadata only to the worker spec."""
+    """prepare public and worker specs with source-authoritative adapter metadata."""
     _require_supported_adapter_continuation(spec)
     ref = spec.train.init_from_adapter
     if not ref:
@@ -776,7 +776,7 @@ def _prepare_init_from_adapter(
     )
     assert metadata is not None
     identity = adapter_artifact_identity(storage, config, token, revision).to_dict()
-    public_spec = spec
+    public_spec = replace(spec, train=replace(spec.train, lora_alpha=metadata.alpha))
     worker_spec = replace(
         worker_spec,
         train=replace(worker_spec.train, lora_rank=metadata.rank, lora_alpha=metadata.alpha),

{freesolo_flash_dev-1.0.0 → freesolo_flash_dev-1.0.2}/flash/runner/verified_revisions.py

@@ -3,13 +3,17 @@
 from __future__ import annotations
 
 import contextlib
-import fcntl
 import json
 import os
 import tempfile
 from collections.abc import Callable, Iterator
 from contextlib import contextmanager
 
+try:
+    import fcntl
+except ImportError:  # pragma: no cover - linux production fails closed below
+    fcntl = None
+
 from flash.schema import parse_adapter_revision
 
 _LEDGER_SUFFIX = ".verified-revisions"
@@ -29,6 +33,8 @@ def _paths(run_id: str) -> tuple[str, str, str]:
 
 @contextmanager
 def _locked_ledger(run_id: str, *, exclusive: bool) -> Iterator[tuple[str, str]]:
+    if fcntl is None:
+        raise RuntimeError("interprocess verified-revision locking is unavailable")
     runs_dir, ledger_path, lock_path = _paths(run_id)
     fd = os.open(lock_path, os.O_CREAT | os.O_RDWR, 0o600)
     with os.fdopen(fd, "a+") as lock_file:

{freesolo_flash_dev-1.0.0 → freesolo_flash_dev-1.0.2}/flash/schema/__init__.py

@@ -546,7 +546,12 @@ def _validate_grpo(spec: JobSpec) -> None:
 
 
 def _validate_opd(spec: JobSpec) -> None:
-    """validate that the opd context budget leaves room for a prompt."""
+    """validate opd-specific training constraints."""
+    if spec.train.kl_penalty_coef == 0.0:
+        raise ConfigError(
+            "[train] kl_penalty_coef must be > 0 for opd because it scales the gkd "
+            "distillation objective; omit it to use the default 1.0 or set a positive value"
+        )
     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
@@ -564,6 +569,9 @@ def _validate_opd(spec: JobSpec) -> None:
                 f"invalid budget fails before a GPU worker is provisioned."
             )
 
+        # short hybrid-mamba contexts are safe because the worker compares vllm's derived scheduler
+        # budget with the catalogued block size and supplies an explicit floor only when required.
+
 
 # Each algorithm's spec-level contract lives in ONE validator, dispatched by name so a new algorithm
 # adds a function + a map entry rather than another scattered ``if spec.algorithm == ...`` block.