AutoGineer
Generated banner for Nvflare Convert Pytorch
Generated logo for Nvflare Convert Pytorch

Nvflare Convert Pytorch

NVIDIAOfficialCreated by NVIDIA FLARE Team

  • Skill
  • Workflow
  • Software development
  • Apache-2.0
  • Medium risk
  • Has scripts
Download ZIP

From the author

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.
— the description by NVIDIA FLARE Team

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured procedure for migrating existing, manual PyTorch training code into an NVFLARE federated learning environment. It focuses on wrapping standard PyTorch training loops, models, and data loaders to support federated model exchange, local validation, and job export. The process emphasizes maintaining the integrity of the original training logic while integrating it into the NVFLARE Client API, ensuring that model parameters, metrics, and optimizer steps are correctly handled across federated rounds.

What it does

  • Inspects existing PyTorch source code to extract training, model, and data loading logic.
  • Generates a federated training client using the NVFLARE Client API.
  • Configures federated jobs using standard recipes like FedAvg.
  • Implements model exchange patterns for PyTorch state_dict objects.
  • Validates the converted job through local simulation and artifact inspection.
  • Exports the final federated job structure for deployment.

When to use it

  • When you have a working, plain PyTorch training script that you want to run in a federated learning setting.
  • When you need to implement model aggregation across multiple sites using PyTorch.
  • When you require local validation of federated training rounds before full-scale deployment.
  • When you need to convert manual training loops into a structured NVFLARE job format.

Advantages

  • Automates the boilerplate required to transition from local to federated training.
  • Ensures consistent handling of model parameters and metric reporting.
  • Provides a validated path for job construction and configuration.
  • Maintains compatibility with standard PyTorch workflows and data structures.

Usage examples

“Convert my existing PyTorch training script to an NVFLARE job.”
The agent will inspect your script, identify the model and training loop, and generate the necessary client.py and job.py files to run it as an NVFLARE federated task.
“How do I add local validation to my PyTorch federated job?”
The agent will guide you through integrating your existing evaluation logic into the NVFLARE Client API, ensuring metrics are correctly reported back to the server.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/nvidia/nvflare-convert-pytorch/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip nvflare-convert-pytorch.zip -d .agents/skills

Documentation by NVIDIA FLARE Team

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.

Files

references/recipe-selection.md

PyTorch Recipe Selection

PyTorch identifies the training framework; it does not determine the federated workflow. Choose the recipe from the user's FL intent and aggregation, state-exchange, privacy, and site-role requirements.

Recipe Discovery, Algorithms, And Selection

Recipe discovery, the algorithm guide (FedAvg, FedProx, FedOpt, SCAFFOLD, Cyclic, Swarm, FedEval), catalog-based selection rules, the HE-not-supported rule, and non-FedAvg recipe rules are shared across the PyTorch recipe family. Follow ../../nvflare-shared/references/pytorch-family-recipe-selection.md for all of them before constructing job.py. This file covers only the plain-PyTorch job.py construction details.

Standard FedAvg Fast Path

For a normal PyTorch-to-FedAvg conversion, keep the job.py recipe construction small and portable. Run recipe show fedavg-pt --format json first and follow ../../nvflare-shared/references/pytorch-family-recipe-construction.md. The example below contains only the workflow-specific constructor values; add optional recipe keywords and decomposers only as directed by that capability profile:

from nvflare.app_opt.pt.recipes.fedavg import FedAvgRecipe
from nvflare.recipe.sim_env import SimEnv

model_args = {"input_size": input_size, "num_classes": num_classes}
recipe_model = {"class_path": "model.ModelClass", "args": model_args}

recipe_kwargs = dict(
    name=job_name,
    min_clients=num_clients,
    num_rounds=num_rounds,
    model=recipe_model,
    train_script="client.py",
    train_args=train_args,
)
# Add only capability-gated keywords confirmed by recipe show, including
# key_metric when the selected execution path delivers that metric to the server.
recipe = FedAvgRecipe(**recipe_kwargs)
# Apply per-site configuration, then capability-gated decomposers, if required.

env = SimEnv(num_clients=num_clients, workspace_root=workspace_root)
run = recipe.execute(env)

Use a recipe model dict with the same constructor arguments used by the client-side model whenever reconstruction depends on any constructor value:

model={"class_path": "model.ModelClass", "args": model_args}

Prefer class_path at recipe construction time; path is the normalized key used in exported job config, and recipes accept it as an alias.

The maintained hello-pt example uses the in-process recipe defaults. The conversion profile may intentionally differ by selecting tensor-native transport and, independently, enabling the server-side disk-offload optimization when the selected recipe exposes those capabilities. The shared construction reference is the single source of truth for their prerequisites, ordering, and decomposer-registration rules.

The server-side recipe model and the client-side training model must construct the same architecture. If the model constructor needs dimensions, class counts, dropout settings, embedding sizes, or other architecture arguments, pass the same values on both sides. Prefer a small shared constant, JSON/config file, or explicit train_args values over hard-coded divergent defaults.

Follow the shared construction reference for key_metric capability, exact client-metric matching, and lower-is-better metric direction.

Use these portable imports when writing custom Job API code:

from nvflare.job_config.api import FedJob
from nvflare.job_config.script_runner import ScriptRunner
from nvflare.recipe.sim_env import SimEnv

Do not inspect large NVFLARE modules to recover these imports unless validation shows that the installed version differs.

Do not infer that per_site_config is required only because recipe metadata mentions it. For standard FedAvg with the same client.py, model.py, and training arguments on all clients, leave per_site_config unset and let the recipe deploy the executor to all clients. Use per_site_config only when at least one site needs a different train_script, train_args, command, external-process setting, framework/exchange setting, or launch behavior.

For non-FedAvg workflows, use the matching recipe from the catalog (see the shared reference above) and keep the PyTorch Client API exchange aligned with that recipe's expected task names, metadata, and parameter format.

Recipe Capabilities And Execution Mode

Follow ../../nvflare-shared/references/pytorch-family-recipe-construction.md for every selected recipe. It owns the capability checks for tensor settings, decomposer registration, best-model naming, and process-based execution mode; do not copy the FedAvg constructor above to a non-FedAvg recipe.

Export Behavior

Export handling is shared across algorithms and frameworks. Follow ../../nvflare-shared/references/conversion-workflow.md for --export, --export-dir, and local command-line parser behavior.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

Security

What our scanner noticed· Medium risk

  • Phrasing that asks for actions without confirmation
  • Large base64-encoded blobs
  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
NVIDIA FLARE Team
Publisher
NVIDIA (Official)
Source
NVIDIA/skills · skills/nvflare-convert-pytorch · commit fce3cca
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE-APACHE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by NVIDIA FLARE Team or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download nvflare-convert-pytorch.zip