nvflare.recipe.fed_task module

class FedTaskRecipe(*, name: str = 'fed_task', task_name: str = 'task', min_clients: int, num_clients: int | None = None, min_responses: int | None = None, timeout: int = 0, task_data: dict | None = None, task_meta: dict | None = None, task_script: str, task_args: str = '', launch_external_process: bool = False, command: str = 'python3 -u', framework: FrameworkType = FrameworkType.RAW, server_expected_format: ExchangeFormat = ExchangeFormat.RAW, params_transfer_type: TransferType = TransferType.FULL, launch_once: bool = True, shutdown_timeout: float = 0.0, client_memory_gc_rounds: int = 0, cuda_empty_cache: bool = False)[source]

Bases: Recipe

A model-free recipe for running one federated task on participating clients.

This recipe is intended for one-round workflows that do not have a global model lifecycle, such as embedding extraction, preprocessing, feature generation, local evaluation, or other client-side jobs coordinated by the server.

Users are responsible for ensuring that task_script accepts the supplied task_args and any task_data or task_meta payloads it consumes. These values become part of the generated job definition and must never contain actual secret values. Secret references are supported in task_args; task_data and task_meta keep references literal, so read secrets from the site environment or mounted files inside the task script instead.

Parameters:

  • name – Name of the federated job. Defaults to “fed_task”.

  • task_name – Name of the task sent to clients. Defaults to “task”.

  • min_clients – Minimum number of clients required to start the job.

  • num_clients – Number of clients to sample for the task. If None, all available clients are used.

  • min_responses – Minimum number of task results to wait for. If None, waits for all selected clients.

  • timeout – Task timeout in seconds. Defaults to 0, meaning no timeout.

  • task_data – Optional params dict sent to each client as FLModel.params. The dict is stored in the job definition and must not contain secret values or secret references.

  • task_meta – Optional metadata dict sent to each client as FLModel.meta. The dict is stored in the job definition and must not contain secret values or secret references.

  • task_script – Path to the client script.

  • task_args – Command line arguments passed to the client script. The string is stored in the job definition and must not contain actual secret values.

  • launch_external_process – Whether to launch the script in an external process.

  • command – Command used when launch_external_process is True.

  • framework – Framework used by ScriptRunner for parameter exchange. Defaults to RAW.

  • server_expected_format – Server-side expected parameter format. Defaults to RAW.

  • params_transfer_type – Parameter transfer type. Defaults to FULL.

  • launch_once – Whether an external process is launched once for the whole job.

  • shutdown_timeout – Seconds to wait before external process shutdown.

  • client_memory_gc_rounds – Run client memory cleanup every N rounds. Set 0 to disable.

  • cuda_empty_cache – Whether client memory cleanup also empties the CUDA cache.

Example

>>> from nvflare.recipe import FedTaskRecipe, SimEnv
>>>
>>> recipe = FedTaskRecipe(
...     name="extract_embeddings",
...     task_name="embed",
...     min_clients=2,
...     task_script="client.py",
...     task_args="--data-root /data --out /tmp/embeddings",
... )
>>> run = recipe.execute(SimEnv(num_clients=2))

This is base class of a recipe. Recipes are implemented by jobs. A concrete recipe must provide the job for recipe implementation.

Security contract – no secrets in recipe parameters:

Recipe parameters (train_args, task_args, eval_args, per_site_config, config overrides, dicts passed to add_client_config/add_server_config, exec params, etc.) can be written in clear text into generated job configuration. These parameters and their nested values must never contain actual passwords, API keys, tokens, private keys, or other credentials. Instead, read secrets from site environment variables or mounted secret files inside your code, or pass a placeholder created with nvflare.recipe.secrets.secret_ref() or nvflare.recipe.secrets.secret_file_ref() at a supported runtime boundary. See nvflare.recipe.secrets for the supported parameter locations.

Before export or run, recipes scan their parameters with heuristics and emit nvflare.recipe.secrets.PotentialSecretWarning when a value looks like an actual secret. The scan is best-effort: absence of a warning does not prove a parameter is safe to share.

Parameters:

job – the job that implements the recipe.