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

Extend `BaseAdapter.load_checkpoint` to transparently resolve a Hugging
Face repo spec (either `hf://owner/repo[/subdir][@rev]` or bare
`owner/repo[/...]`) to a local cache directory via
`huggingface_hub.snapshot_download`, reusing the existing `lora` /
`full` / `state` loading branches unchanged.

Logic priority at `_resolve_checkpoint_path`:
  1. `hf://` prefix -> force HF (overrides any colliding local dir)
  2. Local path exists -> return as-is
  3. Otherwise parse as `owner/repo[/subfolder][@revision]` and download

Multi-node-safe: download gated on `is_local_main_process` (one per
node), not `is_main_process` (one global). On non-shared filesystems
each node populates its own HF cache once; on shared filesystems
huggingface_hub's per-blob `WeakFileLock` dedupes the concurrent
`snapshot_download` calls so only one node transfers bytes.

Fail-fast: narrow `except (RepositoryNotFoundError, HfHubHTTPError)`
re-raised as `FileNotFoundError` with full context (path, repo_id,
subfolder, revision, HF_TOKEN hint) for actionable error messages.

Also updates the `resume_path` help text and normalizes the inline
comment on all 59 example YAMLs to document the new HF support. No
new config fields; `resume_path: Optional[str]` keeps the same shape.

Note: pre-existing black/isort lint debt in the touched src files is
unrelated to this change.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Jayce-Ping

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: