Documentation

Client API Documentation

AdminAgent

stadle.AdminAgent

Class of Admin Agent to register initial base models.

BasicClient

stadle.BasicClient(config_file: str = None, simulation_flag=True, aggregator_ip_address: str = None, reg_port: str = None, exch_port: str = None, model_path: str = None, agent_running: bool = True)

Create BasicClient using passed-in parameters or parameters from config file (passed-in parameters take priority), used to connnect to a STADLE aggregator and begin participation in FL process

Parameters

  • config_file – Specifies the path of the aggregator config file to read parameter values from, if not provided in the respective constructor parameter. Defaults to value of agent_config_path environmental variable (normally set to setups/config_agent.json) if no path is provided.

  • simulation_flag – Determines if client should operate in simulation mode for testing, or production mode; simulation mode uses the default aggregator token and displays debug information at runtime.

  • aggregator_ip_address – IP address of the aggregator instance to connect to.

  • reg_port – Port to be used to create port for registering through aggregator.

  • exch_port – Deprecated

  • model_path – Path to folder used for local storage (client state, id, local and sg models).

  • agent_running – Flag to determine if agent should actively participate in model exchange with aggregator.

Returns

Configured BasicClient object

stadle.BasicClient.send_trained_model(model, perf_values)

Extract weights from locally-trained model and send weights to aggregator.

Parameters

  • model – Locally-trained model to extract weights from.

  • perf_values – A dictionary containing key-value pairs for different performance metrics to be displayed in STADLE Ops. Valid keys are {‘performance’,’accuracy’,’loss_training’,’loss_valid’,’loss_test’,’f_score’,’reward’}.

Returns

False if new aggregated model was received during local training process (nothing sent in this case), True otherwise

stadle.BasicClient.wait_for_sg_model()

Blocking function that waits to receive the aggregated model from the aggregator.

Returns

Model object with aggregated weights from previous round.

stadle.BasicClient.set_bm_obj(model)

Set container model object in IntegratedClient for use when converting to/from agnostic format.

Parameters

model – Used as a container to store aggregated model weights (for ease of use in local training).

stadle.BasicClient.disconnect()

Disconnect client and exit from FL process participation.

IntegratedClient

stadle.IntegratedClient(config_file: str = None, simulation_flag=True, aggregator_ip_address: str = None, reg_port: str = None, exch_port: str = None, model_path: str = None, agent_running: bool = True)

Create IntegratedClient using passed-in parameters or parameters from config file (passed-in parameters take priority), used to connnect to a STADLE aggregator and begin participation in FL process.

Parameters

  • config_file – Specifies the path of the aggregator config file to read parameter values from, if not provided in the respective constructor parameter. Defaults to value of agent_config_path environmental variable (normally set to setups/config_agent.json) if no path is provided.

  • simulation_flag – Determines if client should operate in simulation mode for testing, or production mode; simulation mode uses the default aggregator token and displays debug information at runtime.

  • aggregator_ip_address – IP address of the aggregator instance to connect to.

  • reg_port – Port to be used to create port for registering through aggregator.

  • exch_port – Deprecated

  • model_path – Path to folder used for local storage (client state, id, local and sg models).

  • agent_running – Flag to determine if agent should actively participate in model exchange with aggregator.

Returns

Configured IntegratedClient object

stadle.IntegratedClient.set_training_function(fn, train_data, **kwargs)

Pass model training function, data, and associated arguments to the IntegratedClient for use during local training.

Model training function must take model, data, and keys of kwargs as arguments. It must also return the trained model and a training performance metric (float value).

Parameters

  • fn – Function to perform model training using train_data and kwargs.

  • train_data – Data object provided to training function during FL process.

  • **kwargs –

    Additional required arguments for training function, passed to the function each time it is called.

stadle.IntegratedClient.set_cross_validation_function(fn, cross_validation_data, **kwargs)

Pass model validation function, data, and associated arguments to the IntegratedClient for use during FL process.

Model validation function must take model, data, and keys of kwargs as arguments. It must also return two performance metrics (float values).

Parameters

  • fn – Function to perform model training using cross_validation_data and kwargs.

  • cross_validation_data – Data object provided to validation function during FL process.

  • **kwargs –

    Additional required arguments for validation function, passed to the function each time it is called.

stadle.IntegratedClient.set_testing_function(fn, test_data, **kwargs)

Pass model test function, data, and associated arguments to the IntegratedClient for use at end of FL process.

Model test function must take model, data, and keys of kwargs as arguments. It must also return two performance metrics (float values).

Parameters

  • fn – Function to perform model training using test_data and kwargs.

  • test_data – Data object provided to validation function during FL process.

  • **kwargs –

    Additional required arguments for test function, passed to the function when it is called.

stadle.IntegratedClient.set_termination_function(fn, **kwargs)

Pass agent termination function and associated arguments to the IntegratedClient for use in managing the FL process.

Parameters

  • fn – Function to determine if agent should stop participation and disconnect. Must return either True or False.

  • **kwargs –

    Required arguments for termination function, passed to the function each time it is called.

stadle.IntegratedClient.set_bm_obj(model)

Set container model object in IntegratedClient for use when converting to/from agnostic format.

Parameters

model – Used as a container to store aggregated model weights (for ease of use in local training).

stadle.IntegratedClient.start()

Start FL process defined by functions passed to IntegratedClient. STADLE then manages both the client-side and server-side of FL.

Config File Documentation

Configuration of Agent

This JSON file, for example config_agent.json file, is read by STADLE admin and ML agents for initial setup. Here is the sample content of the JSON file.

 1{
 2    "agent_name": "default_agent"
 3    "model_path": "./data/agent",
 4    "local_model_file_name": "lms.binaryfile",
 5    "semi_global_model_file_name": "sgms.binaryfile",
 6    "state_file_name": "state",
 7    "aggr_ip": "localhost",
 8    "reg_port": "8765",
 9    "init_weights_flag": 1,
10    "token": "stadle12345",
11    "simulation": "False",
12    "exch_port": "0000"
13}

  • agent_name: A unique name of the agent that users can define. - e.g. default_agent

  • model_path: A path to a local director in the agent machine to save local models and some state info. - e.g. ./data/agent

  • local_model_file_name: A file name to save local models in the agent machine. - e.g. lms.binaryfile

  • semi_global_model_file_name: A file name to save the latest semi-global models in the agent machine. - e.g. sgms.binaryfile

  • state_file_name: A file name to store the agent state in the agent machine. - e.g. state

  • aggr_ip: An aggregator IP address for agents to connect. - e.g. localhost, 123.456.789

  • reg_port: A port number used by agents to join an aggregator for the first time. - e.g. 8765

  • init_weights_flag: A flag used for initializing weights. - e.g. 1

  • token: A token that is used for registration process of agents. Agents need to have the same token to be registered in the STADLE system. - e.g. stadle12345

  • simulation: A flag used to enable a simulation mode. - e.g. True

  • exch_port: A port number used to upload local models to an aggregator from an agent. Agents will get to know this port from the communications with an aggregator. - e.g. 7890