[adapter,docs] refactor: hoist HF imports to module top; codify rule

Move the two `huggingface_hub` imports added in the previous commit
out of function bodies and up to the module's import block:

- `from huggingface_hub import snapshot_download` in
  `src/flow_factory/utils/checkpoint.py`
- `from huggingface_hub.errors import RepositoryNotFoundError,
  HfHubHTTPError` in `src/flow_factory/models/abc.py`

`huggingface_hub` is already a hard dependency (`pyproject.toml:39`),
so there is no import-cost concern; lazy-loading only hid the
dependency surface from readers and `isort`.

Codify the rule so this pattern is caught in review going forward:
- Extend constraint X-GenGroup#22 ("Import Style") in
  `.agents/knowledge/constraints.md` with an explicit "Top-level imports
  only" bullet, listing the three sanctioned exceptions (optional deps
  via `try/except ImportError`, backend-gated imports under runtime
  feature checks like DeepSpeed/FSDP, and unresolvable circular imports).
- Add a matching checklist item to the Code Style section of
  `.agents/skills/ff-review/SKILL.md`.

Pre-existing inline FSDP/DeepSpeed imports in `models/abc.py` (lines
~997-1152) are grandfathered under the new rule's exception (b).

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

Author: Jayce-Ping

.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** — no `import` / `from ... import ...` inside function or method bodies (constraint #22). Exceptions: documented optional deps via `try/except ImportError`, or genuine unresolvable circular imports.
 
 ### Documentation
 - [ ] `guidance/` docs updated if behavior changed

src/flow_factory/models/abc.py

@@ -38,6 +38,7 @@
 from peft import get_peft_model, LoraConfig, PeftModel
 
 from huggingface_hub import split_torch_state_dict_into_shards
+from huggingface_hub.errors import RepositoryNotFoundError, HfHubHTTPError
 from accelerate import Accelerator, DistributedType
 from accelerate.state import PartialState
 from accelerate.utils.modeling import (
@@ -1484,8 +1485,6 @@ def _resolve_checkpoint_path(self, path: str) -> str:
         Raises:
             FileNotFoundError: When the spec is neither a local path nor a reachable HF repo.
         """
-        from huggingface_hub.errors import RepositoryNotFoundError, HfHubHTTPError
-
         force_hf = path.startswith(HF_PATH_PREFIX)
         spec = path[len(HF_PATH_PREFIX):] if force_hf else path
 

src/flow_factory/utils/checkpoint.py

@@ -24,6 +24,7 @@
 from typing import Dict, Optional, List, Tuple, Literal
 
 from safetensors.torch import save_file, load_file
+from huggingface_hub import snapshot_download
 
 def mapping_lora_state_dict(
         state_dict: Dict[str, torch.Tensor],
@@ -223,8 +224,6 @@ def download_hf_checkpoint(
             f"expected 'owner/repo' for repo_id, got {repo_id!r}"
         )
 
-    from huggingface_hub import snapshot_download
-
     allow_patterns: Optional[List[str]] = None
     if subfolder:
         # Match the subfolder itself plus everything beneath it.