nvflare-convert-pytorch

---
name: nvflare-convert-pytorch
description: "Convert existing plain or manual PyTorch training code into an NVFLARE federated job using Client API model exchange, local validation, and job export; use when the user names plain PyTorch or preliminary source inspection identifies one plain-PyTorch owner, and not for Lightning, other frameworks, deployment, POC/production lifecycle, 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, pytorch, conversion"
  languages: "python"
  frameworks: "pytorch, nvflare"
  domain: ml
---

# NVFLARE Convert PyTorch

## Use When

Use when converting an existing plain PyTorch training script, `torch.nn.Module`,
manual training loop, `state_dict` workflow, data loader, checkpoint, or metric loop
into an NVFLARE federated training job. Supports horizontal FL, Client API model
exchange with `FLModel`, recipe `aggregator=` hooks, validation, and export.

## Do Not Use When

Do not use for PyTorch Lightning (route to `nvflare-convert-lightning`), Hugging Face Trainer (route to `nvflare-convert-huggingface`), TensorFlow, XGBoost,
scikit-learn, failed jobs (route to
`nvflare-diagnose-job`), federated statistics without training (route to
`nvflare-fed-stats`), or generic PyTorch debugging without FLARE intent. Out of
scope: production deployment, Kubernetes, POC lifecycle, privacy/security policy design,
controller/workflow rewrites outside recipe or Job APIs, experiment search, and
data distribution experiments beyond minimal validation setup. Privacy-protection
requests — HE/encrypted aggregation, differential privacy, and privacy filters — need provisioning/deployment
policy; route onward rather than substituting an unprotected recipe or adding only a disclaimer.
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.

## 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 reading. Fact extraction is static; do not import or execute
   user training modules to discover fields. Extract: training entrypoint,
   model class path and constructor args, checkpoint behavior, train/eval
   functions, data loading, metric names and denominators, local epochs/steps,
   requested client and round counts, source data split or partition evidence,
   tracking evidence, DDP evidence, and any custom aggregation intent.
3. Apply the dependency-install ordering rule in `../nvflare-shared/references/conversion-common.md` before
   any Python command imports user, PyTorch, NVFLARE, or declared dependency
   modules.
4. Select the recipe from the requested FL workflow, not from PyTorch alone. For
   the standard case — the user explicitly requests FedAvg and inspection
   identifies PyTorch — run `nvflare recipe show fedavg-pt --format json`
   directly and construct it; do not add per-site recipe config unless sites
   actually differ. Load
   `../nvflare-shared/references/pytorch-family-recipe-selection.md` (discovery,
   algorithm guide, catalog-based selection, HE-not-supported rule) only for
   ambiguous or non-FedAvg algorithms, reserving `nvflare recipe list` for those
   cases. Use the module, class, and parameters returned by `recipe show` for
   standard `job.py` construction; for `fedavg-pt`, import `FedAvgRecipe` from
   `nvflare.app_opt.pt.recipes.fedavg`, never from `nvflare.recipe`. After every
   `recipe show`, load
   `../nvflare-shared/references/pytorch-family-recipe-construction.md` and
   derive the recipe's construction capabilities. Load
   `references/recipe-selection.md` only when non-FedAvg or execution-mode
   details are needed.
5. Convert training and evaluation as a pair using
   `references/pytorch-client-api-conversion.md`: initialize FLARE, receive an
   `FLModel`, load `params`, evaluate the received global model, train, and
   send an `FLModel` with updated `params`, `metrics`, and the actual completed
   local optimizer-step count in `NUM_STEPS_CURRENT_ROUND`. Adapt the user's
   evaluation code into the packaged evaluation template; if evaluation is
   required but missing, ask or fail closed. Apply the step-1 data-location
   rules to the generated client's data argument.
6. Add or update `job.py` under the shared constructor-serialization rule:
   use explicit `class_path` (or documented `path` alias) plus complete `args`
   whenever reconstruction needs values. Add requested `aggregator=` wiring,
   metric, tensor-transport, server offload, and execution settings derived
   from the shared PyTorch-family construction profile.
7. Validate in a ladder per `../nvflare-shared/references/validation-evidence.md`:
   compile checks, recipe construction, one final full-run path chosen by the
   artifact being validated, with export and package inspection only for the
   selected exported-artifact path. For a local target, inspect the materialized
   configs and packaging evidence after that run. Use
   `references/job-validation.md` for PyTorch-specific failures. Stop at the
   first failed rung and report the product error. Use the environment and
   permission mechanisms supplied by the agent host; do not inspect or enforce
   its security boundary.
8. Report the recipe, changed files, validation status, metrics, and exact
   artifact paths. Load
   `../nvflare-shared/references/metrics-and-artifact-reporting.md` only when
   normal metric artifacts are absent or inconsistent.

## Requirements

- Must audit model constructor arguments before writing `job.py` by reading the
  model module's `__init__` and the selected recipe's `model` parameter from
  `nvflare recipe show <recipe-name> --format json`, not by reading NVFLARE
  library source. Emit the selected recipe's documented `class_path` or `path`
  key plus complete `args` for every required or overridden constructor value;
  a direct `torch.nn.Module` is allowed only when
  unchanged zero-argument defaults reconstruct it. Values must be statically
  clear from literal source, configuration, or supplied metadata. Otherwise ask
  one semantic question when an answer channel exists or fail closed.
- Must follow `../nvflare-shared/references/pytorch-model-exchange.md` and
  `references/pytorch-client-api-conversion.md` for the canonical plain-PyTorch
  payload and round-loop pattern.
- Must apply
  `../nvflare-shared/references/pytorch-family-recipe-construction.md` after
  `recipe show`; it is the canonical policy for optional recipe parameters,
  model selection, tensor transport, server disk offload, and execution mode.
  Never patch a framework-neutral runtime module or register FOBS handlers in
  `client.py`.
- Must convert source evaluation alongside training and return metrics through
  `FLModel.metrics`; must not synthesize metric semantics without source
  evidence.
- Must count completed local optimizer steps in each generated training round
  and send that positive value as `MetaKey.NUM_STEPS_CURRENT_ROUND`. This is the
  FedAvg aggregation weight; do not omit it, reuse a cumulative count, or
  invent a value when the source loop cannot establish it.
- Must load checkpoints with `torch.load(..., weights_only=True)`; a
  checkpoint that needs full unpickling is ask/fail, per
  `references/pytorch-client-api-conversion.md`.
- Must not make non-PyTorch-family skills load
  `../nvflare-shared/references/pytorch-model-exchange.md`; that reference is
  for plain PyTorch, PyTorch Lightning, and Hugging Face Trainer model/state-dict
  exchange only.
- Site partitioning, custom aggregation, the Source Of Truth Boundary, and user
  input/authorization follow `../nvflare-shared/references/conversion-common.md`.

Always read this converter SKILL.md together with
`../nvflare-shared/references/conversion-common.md`. The standard routing,
recipe selection, and reporting path is inline, so common FedAvg does not load
broad policy or algorithm-selection references. Load the client template,
model-exchange reference, validation reference, and aggregator asset only when
their phase needs them. Load other detailed references only for exceptions:

- `../nvflare-shared/references/conversion-workflow.md` for the full conversion
  contract when a case is non-standard;
- `../nvflare-shared/references/site-data-and-paths.md` only for generated site
  partitions, relative-path resolution, or per-site data locations;
- `../nvflare-shared/references/pytorch-family-recipe-selection.md` only for
  ambiguous or non-FedAvg algorithms, and `references/recipe-selection.md` only
  for non-FedAvg or execution-mode construction details not supplied by
  `recipe show`;
- `../nvflare-shared/references/pytorch-family-recipe-construction.md` after
  every `recipe show`;
- `../nvflare-shared/references/dependency-install.md` only when an install is
  needed;
- `../nvflare-shared/references/runtime-output-guidance.md` only for read-only
  source roots or user-chosen output destinations;
- `../nvflare-shared/references/metrics-and-artifact-reporting.md` only when
  metrics are absent or inconsistent;
- `../nvflare-shared/references/validation-evidence.md` before validation, and
  `../nvflare-shared/references/pytorch-model-exchange.md` only for PyTorch-family exchange;
- `references/pytorch-client-api-conversion.md` for Client API conversion, and
  `references/job-validation.md` for PyTorch-specific validation failures.

Do not load every reference preemptively, and do not depend on NVFLARE
repository examples being present in the user's environment.

From nvidia/skills at cf5224d, shown as plain text under its license: Apache-2.0 (permissive). The license text is in skills/nvflare-convert-pytorch/SKILL.md.

• SKILL.md11 KB · 97b10ebe8a85
• BENCHMARK.md11 KB · 8b16a4dd0661
• assets/
• client_with_eval.py4.6 KB · 02c519fd9e53
• evals/
• config.yml295 B · 0e6e2b6f8b89
• evals.json62 KB · d68f38d144a5
• files/
• SOURCE.md3.1 KB · e341d12d6a8c
• checkpoint-pt/
• model.py829 B · 6a6be09bddef
• train.py1.1 KB · e5fcdabca3b0
• data-parallel-pt/
• model.py831 B · 8d19d77f64d0
• train.py1.1 KB · c623f6438cd5
• eval-pt/
• model.py954 B · 8d8c752c3e82
• train.py2.0 KB · b1b7f592ace3
• external-data-pt/
• model.py906 B · 01c337db9478
• train.py2.3 KB · dfe1fb2bad3c
• factory-optimizer/
• train.py1.0 KB · 0cad9a18069f
• gpu-device-pt/
• model.py892 B · 16f3271ac590
• train.py1.1 KB · d00acae559aa
• hello-pt/
• model.py906 B · 01c337db9478
• train.py1.3 KB · a533aa1ddfd9
• injection-pt/
• README.md1.0 KB · b4dd6403c7f4
• config.yaml437 B · da55d12ec4dd
• model.py906 B · 01c337db9478
• requirements.txt316 B · 4e4199484d2f
• train.py2.0 KB · f8913bcc30e3
• state-mismatch-pt/
• checkpoint_manifest.json391 B · aae576a82b24
• model.py880 B · 23c4df945dd7
• train.py712 B · 430bdf859ed5
• references/
• job-validation.md2.1 KB · c5fbb8d21a73
• pytorch-client-api-conversion.md9.1 KB · be6d5873baa2
• recipe-selection.md4.8 KB · e2f636eb563d
• skill-card.md4.3 KB · a718bc5398c3
• skill.oms.sig11 KB · 954d0e4e6314

32 files, 145 KB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.