[adapter,hparams] feat: support resuming from Hugging Face checkpoint paths

.agents/knowledge/constraints.md

@@ -131,6 +131,7 @@ The adapter sets inference dtype for frozen components and training dtype for tr
 - Use relative imports within `flow_factory` package (e.g., `from ..hparams import *`)
 - Use absolute imports for external packages
 - Follow existing wildcard import patterns for `hparams`
+- **Top-level imports only**: All `import` / `from ... import ...` statements MUST live at the top of the module, never inside function bodies, methods, `__init__`, or conditional branches. Sanctioned exceptions: (a) optional dependencies wrapped in `try/except ImportError` (e.g., `deepspeed`, `xformers`); (b) backend-gated imports where the target symbol is only resolvable under a specific runtime backend already selected by a preceding feature check (e.g., DeepSpeed/FSDP submodules guarded by `is_deepspeed()` / `is_fsdp2()` in `models/abc.py`); (c) genuine unresolvable circular imports documented inline. Lazy imports added merely for "import speed" or "to keep the module light" are NOT acceptable — every hard dependency already runs through Python's import machinery on a typical import path. Inline imports hide the dependency surface from readers, `isort`, and static-analysis tools, and re-execute on every call in hot loops.
 
 ### 23. Type Annotations
 All public methods must have type annotations. Use `typing` module types (`List`, `Dict`, `Optional`, `Tuple`, `Union`) for Python 3.10 compatibility.

.agents/skills/ff-review/SKILL.md

@@ -60,6 +60,7 @@ git status             # Modified files
 - [ ] English comments and docstrings
 - [ ] Apache 2.0 license header on new files
 - [ ] No unnecessary wildcard imports (except `hparams`)
+- [ ] **Top-level imports only** (constraint #22) — see that file for the three sanctioned exceptions (optional deps via `try/except ImportError`, backend-gated runtime feature checks like DeepSpeed/FSDP, unresolvable circular imports).
 
 ### Documentation
 - [ ] `guidance/` docs updated if behavior changed

examples/awm/lora/flux1/default.yaml

@@ -23,7 +23,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "black-forest-labs/FLUX.1-dev"  # HuggingFace model ID or local path
   model_type: "flux1"
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
   # attn_backend: '_flash_3_hub'
 

examples/awm/lora/flux2_klein_base/default.yaml

@@ -23,7 +23,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "black-forest-labs/FLUX.2-klein-base-4B"  # Options: black-forest-labs/FLUX.2-klein-base-4B, black-forest-labs/FLUX.2-klein-base-9B
   model_type: "flux2-klein"
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
   # attn_backend: '_flash_3_hub' # Attention backend for training.
 

examples/awm/lora/sd3_5/default.yaml

@@ -24,7 +24,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "stabilityai/stable-diffusion-3.5-medium"
   model_type: "sd3-5"
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
   # attn_backend: '_flash_3_hub' # Attention backend for training.
 

examples/crd/lora/sd3_5/default.yaml

@@ -25,7 +25,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "stabilityai/stable-diffusion-3.5-medium"
   model_type: "sd3-5"
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
   # attn_backend: '_flash_3_hub' # Attention backend for training.
 

examples/dgpo/lora/sd3_5/default.yaml

@@ -48,7 +48,7 @@ model:
   target_modules: "default"
   model_name_or_path: "stabilityai/stable-diffusion-3.5-medium"  # config.pretrained.model
   model_type: "sd3-5"
-  resume_path: null
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null
 
 # Training Configuration

examples/dgpo/lora/sd3_5/nocfg.yaml

@@ -39,7 +39,7 @@ model:
   target_modules: "default"
   model_name_or_path: "stabilityai/stable-diffusion-3.5-medium"  # config.pretrained.model
   model_type: "sd3-5"
-  resume_path: null
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null
 
 # Training Configuration

examples/dpo/lora/sd3_5/default.yaml

@@ -50,7 +50,7 @@ model:
   target_modules: "default"
   model_name_or_path: "stabilityai/stable-diffusion-3.5-medium"  # Same as flow_grpo
   model_type: "sd3-5"
-  resume_path: null
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null
 
 log:

examples/grpo/full/flux1/default.yaml

@@ -21,7 +21,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "black-forest-labs/FLUX.1-dev"  # HuggingFace model ID or local path
   model_type: "flux1"
-  resume_path: null # Directory contains previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/full/flux1_kontext/default.yaml

@@ -21,7 +21,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "black-forest-labs/FLUX.1-Kontext-dev"  # HuggingFace model ID or local path
   model_type: "flux1-kontext"
-  resume_path: null # Directory contains previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/full/flux2/i2i.yaml

@@ -24,7 +24,7 @@ model:
   target_modules: ["attn.to_q", "attn.to_k", "attn.to_v", "attn.to_out.0"]
   model_name_or_path: "black-forest-labs/FLUX.2-dev"  # HuggingFace model ID or local path
   model_type: "flux2"  # Options: flux1, flux1-kontext, flux2, qwenimage, qwenimage-edit
-  resume_path: null # Directory contains previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/full/flux2/t2i.yaml

@@ -24,7 +24,7 @@ model:
   target_modules: ["attn.to_q", "attn.to_k", "attn.to_v", "attn.to_out.0"]
   model_name_or_path: "black-forest-labs/FLUX.2-dev"  # HuggingFace model ID or local path
   model_type: "flux2"  # Options: flux1, flux1-kontext, flux2, qwenimage, qwenimage-edit
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/full/flux2_klein/default.yaml

@@ -21,7 +21,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "black-forest-labs/FLUX.2-klein-4B"  # Options: black-forest-labs/FLUX.2-klein-4B, black-forest-labs/FLUX.2-klein-9B
   model_type: "flux2-klein"
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/full/flux2_klein_base/default.yaml

@@ -21,7 +21,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "black-forest-labs/FLUX.2-klein-base-4B"  # Options: black-forest-labs/FLUX.2-klein-base-4B, black-forest-labs/FLUX.2-klein-base-9B
   model_type: "flux2-klein"
-  resume_path: null # Directory contains previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/full/qwen_image/default.yaml

@@ -22,7 +22,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "Qwen/Qwen-Image"  # HuggingFace model ID or local path
   model_type: "qwen-image"  # Options: flux1, flux1-kontext, flux2, qwenimage, qwenimage-edit
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
   # attn_backend: '_flash_3_varlen_hub' # Attention backend for Qwen-Image Series, which uses masked attention with variable sequence length.
 

examples/grpo/full/qwen_image_edit_plus/default.yaml

@@ -21,7 +21,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "Qwen/Qwen-Image-Edit-2509"  # Qwen/Qwen-Image-Edit-2509 or Qwen/Qwen-Image-Edit-2511
   model_type: "qwen-image-edit-plus"
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
   # attn_backend: '_flash_3_varlen_hub' # Attention backend for Qwen-Image Series, which uses masked attention with variable sequence length.
 

examples/grpo/full/sd3_5/default.yaml

@@ -21,7 +21,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "stabilityai/stable-diffusion-3.5-medium"  # HuggingFace model ID or local path
   model_type: "sd3-5"  # Options: flux1, flux1-kontext, flux2, qwenimage, qwenimage-edit, sd3-5
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/full/wan21/i2v.yaml

@@ -22,7 +22,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "Wan-AI/Wan2.1-I2V-14B-480P-Diffusers"  # Wan-AI/Wan2.1-I2V-14B-480P-Diffusers / Wan-AI/Wan2.1-I2V-14B-720P-Diffusers
   model_type: "wan2_i2v"  # wan2_t2v, wan2_i2v, wan2_v2v
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/full/wan21/t2v.yaml

@@ -22,7 +22,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "Wan-AI/Wan2.1-T2V-14B-Diffusers"  # Wan-AI/Wan2.1-T2V-14B-Diffusers / Wan-AI/Wan2.2-T2V-A14B-Diffusers
   model_type: "wan2_t2v"  # wan2_t2v, wan2_i2v, wan2_v2v
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/full/wan22/i2v.yaml

@@ -28,7 +28,7 @@ model:
   target_modules: "default"
   model_name_or_path: "Wan-AI/Wan2.2-I2V-A14B-Diffusers" # Wan-AI/Wan2.2-TI2V-5B-Diffusers / Wan-AI/Wan2.2-I2V-A14B-Diffusers
   model_type: "wan2_i2v"  # wan2_t2v, wan2_i2v, wan2_v2v
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/full/wan22/t2v.yaml

@@ -28,7 +28,7 @@ model:
   target_modules: "default"
   model_name_or_path: "Wan-AI/Wan2.2-T2V-A14B-Diffusers"  # Wan-AI/Wan2.1-T2V-14B-Diffusers / Wan-AI/Wan2.2-T2V-A14B-Diffusers
   model_type: "wan2_t2v"  # wan2_t2v, wan2_i2v, wan2_v2v
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/full/z_image/default.yaml

@@ -22,7 +22,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "Tongyi-MAI/Z-Image"  # Options: Tongyi-MAI/Z-Image, Tongyi-MAI/Z-Image-Turbo
   model_type: "z-image"
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/full/z_image_turbo/default.yaml

@@ -22,7 +22,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "Tongyi-MAI/Z-Image-Turbo"  # HuggingFace model ID or local path
   model_type: "z-image"
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/lora/flux1/default.yaml

@@ -23,7 +23,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "black-forest-labs/FLUX.1-dev"  # HuggingFace model ID or local path
   model_type: "flux1"  # Options: flux1, flux1-kontext, flux2, qwenimage, qwenimage-edit
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/lora/flux1_kontext/default.yaml

@@ -23,7 +23,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "black-forest-labs/FLUX.1-Kontext-dev"  # HuggingFace model ID or local path
   model_type: "flux1-kontext"
-  resume_path: null # Directory contains previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/lora/flux2/i2i.yaml

@@ -23,7 +23,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "black-forest-labs/FLUX.2-dev"  # HuggingFace model ID or local path
   model_type: "flux2"
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/lora/flux2/t2i.yaml

@@ -23,7 +23,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "black-forest-labs/FLUX.2-dev"  # HuggingFace model ID or local path
   model_type: "flux2"
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/lora/flux2_klein/default.yaml

@@ -23,7 +23,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "black-forest-labs/FLUX.2-klein-9B"  # Options: black-forest-labs/FLUX.2-klein-4B, black-forest-labs/FLUX.2-klein-9B
   model_type: "flux2-klein"
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/lora/flux2_klein_base/default.yaml

@@ -23,7 +23,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "black-forest-labs/FLUX.2-klein-base-9B"  # Options: black-forest-labs/FLUX.2-klein-base-4B, black-forest-labs/FLUX.2-klein-base-9B
   model_type: "flux2-klein"
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/lora/ltx2/i2av.yaml

@@ -28,7 +28,7 @@ model:
   target_modules: "default"  # 28 Linear layers per block (video/audio attn + cross-modal attn + FFN)
   model_name_or_path: "Lightricks/LTX-2"  # Options: Lightricks/LTX-2, dg845/LTX-2.3-Diffusers
   model_type: "ltx2_i2av"
-  resume_path: null  # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null  # Options: lora, full, state. Null to auto-detect based on `finetune_type`
 
 log:

examples/grpo/lora/ltx2/t2av.yaml

@@ -27,7 +27,7 @@ model:
   target_modules: "default"  # 28 Linear layers per block (video/audio attn + cross-modal attn + FFN)
   model_name_or_path: "Lightricks/LTX-2"  # Options: Lightricks/LTX-2, dg845/LTX-2.3-Diffusers
   model_type: "ltx2_t2av"
-  resume_path: null  # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null  # Options: lora, full, state. Null to auto-detect based on `finetune_type`
   # attn_backend: '_flash_3_hub'  # Attention backend.
 

examples/grpo/lora/ltx2/t2av_pickscore.yaml

@@ -25,7 +25,7 @@ model:
   target_modules: "default"  # 28 Linear layers per block (video/audio attn + cross-modal attn + FFN)
   model_name_or_path: "dg845/LTX-2.3-Diffusers"  # Options: Lightricks/LTX-2, dg845/LTX-2.3-Diffusers
   model_type: "ltx2_t2av"
-  resume_path: null  # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null  # Options: lora, full, state. Null to auto-detect based on `finetune_type`
   # attn_backend: '_flash_3_hub'  # Attention backend.
 

examples/grpo/lora/qwen_image/default.yaml

@@ -23,7 +23,7 @@ model:
   target_modules: "default" # Options: all, default, or list of module names like ["to_k", "to_q", "to_v", "to_out.0"]
   model_name_or_path: "Qwen/Qwen-Image-2512"  # Qwen/Qwen-Image or Qwen/Qwen-Image-2512
   model_type: "qwen-image"
-  resume_path: null # Path to load previous checkpoint/lora adapter
+  resume_path: null # Local path or HF repo id (e.g. 'owner/repo[/subdir][@rev]') for previous checkpoint/lora adapter
   resume_type: null # Options: lora, full, state. Null to auto-detect based on `finetune_type`
   # attn_backend: '_flash_3_varlen_hub' # Attention backend for Qwen-Image Series, which uses masked attention with variable sequence length.