nvflare-convert-pytorch

Files (32)

• BENCHMARK.md
• SKILL.md
• client_with_eval.py · assets/
• config.yml · evals/
• evals.json · evals/
• SOURCE.md · evals/files/
• model.py · evals/files/checkpoint-pt/
• train.py · evals/files/checkpoint-pt/
• model.py · evals/files/data-parallel-pt/
• train.py · evals/files/data-parallel-pt/
• model.py · evals/files/eval-pt/
• train.py · evals/files/eval-pt/
• model.py · evals/files/external-data-pt/
• train.py · evals/files/external-data-pt/
• train.py · evals/files/factory-optimizer/
• model.py · evals/files/gpu-device-pt/
• train.py · evals/files/gpu-device-pt/
• model.py · evals/files/hello-pt/
• train.py · evals/files/hello-pt/
• README.md · evals/files/injection-pt/
• config.yaml · evals/files/injection-pt/
• model.py · evals/files/injection-pt/
• requirements.txt · evals/files/injection-pt/
• train.py · evals/files/injection-pt/
• checkpoint_manifest.json · evals/files/state-mismatch-pt/
• model.py · evals/files/state-mismatch-pt/
• train.py · evals/files/state-mismatch-pt/
• job-validation.md · references/
• pytorch-client-api-conversion.md · references/
• recipe-selection.md · references/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# 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`.

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills