nvflare.edge.model_protocol module

Model exchange protocol specification and utilities.

This module defines the complete protocol for exchanging models between components, including message format specification, supported types, and validation utilities.

Example

>>> from nvflare.edge.utils.model_protocol import ModelBufferType, ModelExchangeFormat
>>> task_dxo = {
...     "data": encoded_data,
...     "meta": {
...         ModelExchangeFormat.MODEL_BUFFER_TYPE: ModelBufferType.EXECUTORCH,
...         ModelExchangeFormat.MODEL_BUFFER_NATIVE_FORMAT: ModelNativeFormat.BINARY,
...         ModelExchangeFormat.MODEL_BUFFER_ENCODING: ModelEncoding.BASE64
...     }
... }
>>> verify_payload(
...     payload,
...     expected_type=ModelBufferType.EXECUTORCH
... )

class ModelBufferType

Bases: object

Supported model buffer types for data exchange.

These constants define the supported types of data that can be exchanged, helping ensure consistency across different components.

EXECUTORCH = 'executorch'

PYTORCH = 'pytorch'

class ModelEncoding

Bases: object

Supported encodings for data transmission.

For binary native format:

• BASE64 or HEX encoding required for safe transmission

For string native format:

• UTF8 or ASCII for character encoding

• NONE for plain string data

ASCII = 'ascii'

BASE64 = 'base64'

HEX = 'hex'

NONE = 'none'

UTF8 = 'utf8'

class ModelExchangeFormat

Bases: object

Constants for model exchange protocol between components.

The protocol uses three main attributes: 1. TYPE: What the data represents (e.g., executorch, pytorch) 2. NATIVE_FORMAT: Original format before any transmission encoding 3. ENCODING: How the data is encoded for transmission

Format and Encoding combinations:

• For binary FORMAT:

  • base64 encoding (safe for text transmission)

  • hex encoding (alternative text encoding)

• For string FORMAT:

  • utf8 encoding (for unicode text)

  • ascii encoding (for restricted character set)

  • null/empty (for plain string)

Examples

Binary data (ExecutorTorch model):

{

“data”: <encoded_data>, “meta”: {

MODEL_BUFFER_TYPE: ModelBufferType.EXECUTORCH, MODEL_BUFFER_NATIVE_FORMAT: ModelNativeFormat.BINARY, MODEL_BUFFER_ENCODING: ModelEncoding.BASE64

}

}

String data (JSON config):

{

“data”: <json_string>, “meta”: {

MODEL_BUFFER_TYPE: ModelBufferType.JSON, MODEL_BUFFER_NATIVE_FORMAT: ModelNativeFormat.STRING, MODEL_BUFFER_ENCODING: ModelEncoding.UTF8

}

}

MODEL_BUFFER_ENCODING = 'model_buffer_encoding'

MODEL_BUFFER_NATIVE_FORMAT = 'model_buffer_native_format'

MODEL_BUFFER_TYPE = 'model_buffer_type'

MODEL_VERSION = 'model_version'

class ModelNativeFormat

Bases: object

Native format of the data before any transmission encoding.

BINARY = 'binary'

STRING = 'string'

verify_payload(task_dxo: DXO, expected_type: str | None = None, expected_format: str | None = None, expected_encoding: str | None = None) → Dict

Verify that the task data payload follows the model exchange protocol.

Parameters:

• task_dxo – The task data dxo to verify

• expected_type – Expected model buffer type (from ModelBufferType)

• expected_format – Expected native format (from ModelNativeFormat)

• expected_encoding – Expected encoding (from ModelEncoding)

Raises:

ValueError – If the payload structure is invalid or values don’t match expected