/nvflare-convert-huggingface

name: nvflare-convert-huggingface
description: "Convert existing Hugging Face Transformers Trainer or TRL SFTTrainer training code into an NVFLARE federated job using flare.patch(trainer), local validation, and job export; use when the user names Hugging Face or preliminary source inspection identifies one Hugging Face owner, and not for manual PyTorch loops, Lightning, inference-only pipelines, deployment, or experiment workflows."
license: Apache-2.0
metadata:
  version: "0.1.0"
  author: "NVIDIA FLARE Team <federatedlearning@nvidia.com>"
  min-flare-version: "2.9.0"
  blast-radius: runs_simulator
  category: Conversion
  tags: "nvflare, federated-learning, huggingface, transformers, trl, peft, conversion"
  languages: "python"
  frameworks: "huggingface, transformers, trl, pytorch, nvflare"
  domain: ml

NVFLARE Convert Hugging Face

Use When

Use when converting training code built around `transformers.Trainer`, `Seq2SeqTrainer`, TRL `SFTTrainer`, or another Trainer subclass. Support full-model and PEFT/LoRA fine-tuning, datasets/tokenizers, Trainer callbacks and metrics, checkpoint continuity, and replicated `torch.distributed` training.

Do Not Use When

Do not use for an `AutoModel` driven by a manual PyTorch loop without a Hugging Face Trainer (route to `nvflare-convert-pytorch`), PyTorch Lightning (route to `nvflare-convert-lightning`, including Lightning modules that contain Transformers models), inference-only pipelines, model serving, failed jobs (route to `nvflare-diagnose-job`), or federated statistics without training (route to `nvflare-fed-stats`). Route a project with active Lightning and Hugging Face Trainer entrypoints to `nvflare-orient` to select one training-loop owner or separate jobs. Route unresolved Trainer ownership, such as a Trainer factory without a bound owner call, to `nvflare-orient`; do not patch either Trainer. Out of scope: DeepSpeed, FSDP, production/POC deployment, controller rewrites, experiment search, and privacy-protection requests such as HE, encrypted aggregation, differential privacy, or privacy filters; never substitute an unprotected recipe or present a disclaimer as implementation. If a request combines federated statistics and model-training conversion, treat it as two independent jobs and workflows: do not merge or automatically chain them, do not route the combination to `nvflare-orient`, and ask which workflow to run first before generating or running either job. Recommend `nvflare-fed-stats` first only when the user's purpose is to understand data distribution; handle conversion later as a separate request.

Available Scripts

| Script | Purpose | Arguments | | --- | --- | --- | | `scripts/resolve_model_snapshot.py` | Resolve a local or Hub model/dataset snapshot and emit JSON evidence. | Identifier; required `--source`; optional source-root, download, revision, cache, and repository-type flags. |

Use `run_script()` only during the validation phase after loading `references/huggingface-validation.md`. For example:

• `run_script("scripts/resolve_model_snapshot.py", ["--source", "local", "--source-root", "<absolute-source-root>", "<configured-path>"])`
• `run_script("scripts/resolve_model_snapshot.py", ["--source", "hub", "<org/model>"])`

Workflow

1. Load `../nvflare-shared/references/conversion-common.md` and apply it for the whole conversion; this SKILL.md states only the framework-specific deltas. Load `../nvflare-shared/references/conversion-workflow.md` only for a non-standard rerun, authorization, or missing-semantics case; it no longer holds the data-location or partitioning contracts, whose invariants `conversion-common.md` owns. Load `../nvflare-shared/references/site-data-and-paths.md` for generated partitions, relative paths, or per-site data locations. 2. Inspect before editing with `nvflare agent inspect source <path> --format json` plus direct source reading. Load `references/huggingface-detection.md` during this phase. If inspect recommends `nvflare-orient` for unresolved Trainer ownership or active Lightning/Hugging Face owners, stop before editing. Extract the entrypoint, Trainer subclass, model constructor, tokenizer or processor, datasets and collator, Trainer arguments, `compute_metrics`, callbacks, checkpoint and PEFT settings, precision, local budget, distributed launcher, site/round counts, data location, and aggregation intent. Do not import or execute user training modules to discover them. 3. Apply the dependency-install ordering rule in `../nvflare-shared/references/conversion-common.md` before any Python command imports user, framework, NVFLARE, or declared dependencies. Keep dependency inventory single-purpose: check NVFLARE separately, inventory non-product packages separately, and do not append Hugging Face cache or filesystem discovery. Defer model and dataset availability checks to the maintained resolver during validation. If an optional path must be inspected, run it separately and report a missing directory with exit code zero. 4. Select the recipe from FL intent. For explicit FedAvg, run `nvflare recipe show fedavg-pt --format json`, then immediately load `../nvflare-shared/references/pytorch-family-recipe-construction.md` and use the returned module, class, and parameters with the required construction and execution shape in `assets/job.py`. Import `FedAvgRecipe` from `nvflare.app_opt.pt.recipes.fedavg`, never from `nvflare.recipe`. Treat `class_path` as the public recipe key and `path` as its normalized exported representation; do not inspect Recipe source or signatures to reconcile them. Do not guess adjacent symbols or add per-site recipe config unless sites genuinely differ. Load `../nvflare-shared/references/pytorch-family-recipe-selection.md` only for ambiguous, evaluation-only, or non-FedAvg requests. 5. Convert with `references/huggingface-conversion.md` and adapt `assets/client_with_eva