MPAI-AIF Basic API

It is assumed that all the communication between the Controller and the Store occur via https protocol. Thus, the APIs reported refer to the http secure protocol functions (i.e. GET, POST, etc). The Store supports the GIT protocol [1].

The Controller implements the functions relative to the file retrieval as described in 8.1.1.

1.1 Get and parse archive

Get and parse an archive from the Store.

1.1.1 MPAI_AIFS_GetAndParseArchive

error_t MPAI_AIFS_GetAndParseArchive(const char* filename)

The default file format is tar.gz. Options are tar.gz, tar.bz2, tbz, tbz2, tb2, bz2, tar, and zip. For example, specifying archive.zip would send an archive in ZIP format [5]. The archive shall include one AIW Metadata file and one or more binary files. The parsing of JSON Metadata and the creation of the corresponding data structure is left to the Implementer.

All archives downloaded from the Store shall not leave the Trusted Zone if the AIF Profile is Basic and shall not leave the Secure Storage if the AIF Profile is Secure.

2 Controller API called by User Agent

2.1 General

This section specifies functions executed by the User Agent when interacting with the Controller. In particular:

Initialise all the Components of the AIF.
Start/Stop/Suspend/Resume AIWs.
Manage Resource Allocation.

2.1.1 MPAI_AIFU_Controller_Initialize

error_t MPAI_AIFU_Controller_Initialize()

This function, called by the User Agent, switches on and initialies the Controller, in particular the Communication Component.

2.1.2 MPAI_AIFU_Controller_Destroy

error_t MPAI_AIFU_Controller_Destroy()

This function, called by the User Agent, switches off the Controller, after data structures related to running AIWs have been disposed of.

2.2 Start/Pause/Resume/Stop Messages to other AIWs

These functions can be used by the User Agent to send messages from the Controller to AIWs. Errors encountered while transmitting/receiving these Messages are non-recoverable – i.e., they terminate the entire AIW. AIWs can communicate with other AIWs and the Controller uses this API to Start/Pause/Resume/Stop the AIWs.

2.2.1 MPAI_AIFU_AIW_Start

error_t MPAI_AIFU_AIW_Start(const char* name, int* AIW_ID)

This function, called by the User Agent, registers with the Controller and starts an instance of the AIW named name. The AIW Metadata for name shall have been previously parsed. The AIW ID is returned in the variable AIW_ID. If the operation succeeds, it has immediate effect.

2.2.2 MPAI_AIFU_AIW_Pause

error_t MPAI_AIFU_AIW_Pause(int AIW_ID)

With this function the User Agent asks the Controller to pause the AIW with ID AIW_ID. If the operation succeeds, it has immediate effect.

2.2.3 MPAI_AIFU_AIW_Resume

error_t MPAI_AIFU_AIW_Resume(int AIW_ID)

With this function the User Agent asks the Controller to resume the AIW with ID AIW_ID. If the operation succeeds, it has immediate effect.

2.2.4 MPAI_AIFU_AIW_Stop

error_t MPAI_AIFU_AIW_Stop(int AIW_ID)

This function, called by the User Agent, deregisters and stops the AIW with ID AIW_ID from the Controller. If the operation succeeds, it has immediate effect.

2.3 Inquire about state of AIWs and AIMs

2.3.1 MPAI_AIFU_AIM_GetStatus

error_t MPAI_AIFU_AIM_GetStatus(int AIW_ID, const char* name, int* status)

With this function the User Agent inquires about the current status of the AIM named name belonging to AIW with ID AIW_ID. The status is returned in status. Admissible values are: MPAI_AIM_ALIVE, MPAI_AIM_DEAD.

2.4 Management of Shared and AIM Storage for AIWs

2.4.1 MPAI_AIFU_SharedStorage_Init

error_t MPAI_AIFU_SharedStorage_init(int AIW_ID)

With this function the User Agent initialises the Shared Storage interface for the AIW with ID AIW_ID.

2.4.2 MPAI_AIFU_ AIMStorage_Init

error_t MPAI_AIFU_ AIMStorage_init(int AIM_ID)

With this function the User Agent initialises the AIM Storage interface for the AIW with ID AIW_ID.

2.5 Communication management

Communication takes place with Messages communicated via Events or Ports and Channels. Their actual implementation and signal type depends on the MPAI-AIF Implementation (and hence on the specific platform, operating system, and programming language the Implementation is developed for). Events are defined AIF wide while Ports, Channels and Messages are specific to the AIM and thus part of the AIM API.

2.5.1 MPAI_AIFU_Communication_Event

error_t MPAI_AIFU_Communication_Event(const char* event)

With this function the User Agent initialises the event handling for Event named event.

2.6 Resource allocation management

2.6.1 MPAI_AIFU_Resource_GetGlobal

error_t MPAI_AIFU_Resource_GetGlobal(const char* key, const char* min_value, const char* max_value, const char* requested_value)

With this function the User Agent interrogates the resource allocation for one AIF Metadata entry.

2.6.2 MPAI_AIFU_Resource_SetGlobal

error_t MPAI_AIFU_Resource_SetGlobal(const char* key, const char* min_value, const char* max_value, const char* requested_value)

With this function the User Agent initialises the resource allocation for one AIF Metadata entry.

2.6.3 MPAI_AIFU_Resource_GetAIW

error_t MPAI_AIFU_Resource_GetAIW(int AIW_ID, const char* key, const char* min_value, const char* max_value, const char* requested_value)

With this function the User Agent interrogates the resource allocation for one AIM Metadata entry for the AIW with AIW ID AIW_ID.

2.6.4 MPAI_AIFU_Resource_SetAIW

error_t MPAI_AIFU_Resource_SetAIW(int AIW_ID, const char* key, const char* min_value, const char* max_value, const char* requested_value)

With this function the User Agent interrogates the resource allocation for one AIM Metadata entry for the AIW with AIW ID AIW_ID.

3 Controller API called by AIMs

3.1 General

The following API have been defined in Version 1.1. They specify how AIWs:

Define the topology and connections of AIMs in the AIW.
Define the Time base.
Define the Resource Policy.

3.2 Resource allocation management

3.2.1 MPAI_AIFM_Resource_GetGlobal

error_t MPAI_AIFM_Resource_GetGlobal(const char* key, const char* min_value, const char* max_value, const char* requested_value)

With this function the AIM interrogates the resource allocation for one AIF Metadata entry.

3.2.2 MPAI_AIFM_Resource_SetGlobal

error_t MPAI_AIFM_Resource_SetGlobal(const char* key, const char* min_value, const char* max_value, const char* requested_value)

With this function the AIM initialises the resource allocation for one AIF Metadata entry.

3.2.3 MPAI_AIFM_Resource_GetAIW

error_t MPAI_AIFM_Resource_GetAIW(int AIW_ID, const char* key, const char* min_value, const char* max_value, const char* requested_value)

With this function the AIM interrogates the resource allocation for one AIM Metadata entry for the AIW with AIW ID AIW_ID.

3.2.4 MPAI_AIFM_Resource_SetAIW

error_t MPAI_AIFM_Resource_SetAIW(int AIW_ID, const char* key, const char* min_value, const char* max_value, const char* requested_value)

With this function the AIM interrogates the resource allocation for one AIM Metadata entry for the AIW with AIW ID AIW_ID.

3.3 Register/deregister AIMs with the Controller

3.3.1 MPAI_AIFM_AIM_Register_Local

error_t MPAI_AIFM_AIM_Register_Local(const char* name)

With this function the AIM registers the AIM named name with the Controller. The AIM shall be defined in the AIM Metadata. An Implementation that can be run on the Controller shall have been downloaded from the Store together with the Metadata or be available in the AIM Storage after having been downloaded from the Store together with the Metadata.

3.3.2 MPAI_AIFM_AIM_Register_Remote

error_t MPAI_AIFM_AIM_Register_Remote(const char* name, const char* uri)

With this function the AIM registers the AIM named name with the Controller. The AIM shall be defined in the AIM Metadata. An implementation that can be run on the Controller shall have been downloaded from the Store together with the Metadata or be available locally. The AIM will be run remotely on the MPAI Server identified by uri.

3.3.3 MPAI_AIFM_AIM_Deregister

error_t MPAI_AIFM_AIM_Deregister(const char* name)

The AIW deregisters the AIM named name from the Controller.

3.4 Send Start/Pause/Resume/Stop Messages to other AIMs

AIMs can send Messages to AIMs defined in its Metadata.

Errors encountered while transmitting/receiving these Messages are non-recoverable – i.e., they terminate the entire AIM. AIMs can communicate with other AIMs and the Controller uses this API to Start/Pause/Resume/Stop the AIMs.

3.4.1 MPAI_AIFM_AIM_Start

error_t MPAI_AIFM_AIM_Start(const char* name)

With this function the AIM asks the Controller to start the AIM named name. If the operation succeeds, it has immediate effect.

3.4.2 MPAI_AIFM_AIM_Pause

error_t MPAI_AIFM_AIM_Pause(const char* name)

With this function the AIM asks the Controller to pause the AIM named name. If the operation succeeds, it has immediate effect.

3.4.3 MPAI_AIFM_AIM_Resume

error_t MPAI_AIFM_AIM_Resume(const char* name)

With this function the AIM asks the Controller to resume the AIM named name. If the operation succeeds, it has immediate effect.

3.4.4 MPAI_AIFM_AIM_Stop

error_t MPAI_AIFM_AIM_Stop(const char* name)

With this function the AIM asks the Controller to stop the AIM named name. If the operation succeeds, it has immediate effect.

1.3.4.5 MPAI_AIFM_AIM_EventHandler

error_t MPAI_AIFM_AIM_EventHandler(const char* name)

The AIF creates EventHandler for the AIW with given name name. If the operation succeeds, it has immediate effect.

3.5 Register Connections between AIMs

3.5.1 MPAI_AIFM_Channel_Create

error_t
MPAI_AIFM_Channel_Create(const char* name, const char* out_AIM_name, const char* out_port_name, const char* in_AIM_name, const char* in_port_name)

With this function the AIM asks the Controller to create a new interconnecting channel between an output port and an input port. AIM and port names are specified with the name used when constructed.

3.5.2 MPAI_AIFM_Channel_Destroy

error_t MPAI_AIFM_Channel_Destroy(const char* name)

With this function the AIM asks the Controller to destroy the channel with name name. This API Call closes all Ports related to the Channel.

3.6 Using Ports

3.6.1 MPAI_AIFM_Port_Output_Read

message_t* MPAI_AIFM_Port_Output_Read(
const char* AIM_name, const char* port_name)

This function reads a message from the Port identified by (AIM_name,port_name). The read is blocking. Hence, in order to avoid deadlocks, the Implementation should first probe the Port with MPAI_AIF_Port_Probe. It returns a copy of the original Message.

3.6.2 MPAI_AIFM_Port_Input_Write

error_t MPAI_AIFM_Port_Input_Write(
const char* AIM_name, const char* port_name, message_t* message)

This function writes a message message to the Port identified by (AIM_name,port_name). The write is blocking. Hence, in order to avoid deadlocks the Implementation should first probe the Port with MPAI_AIF_Port_Probe. The Message being transmitted shall remain available until the function returns, or the behaviour will be undefined.

3.6.3 MPAI_AIFM_Port_Reset

error_t MPAI_AIFM_Port_Reset(const char* AIM_name, const char* port_name)

This function resets an input or output Port identified by (AIM_name,port_name) by deleting all the pending Messages associated with it.

3.6.4 MPAI_AIFM_Port_CountPendingMessages

size_t MPAI_AIFM_Port_CountPendingMessages(
const char* AIM_name, const char* port_name)

This function returns the number of pending messages on a input or output Port identified by (AIM_name,port_name).

3.6.5 MPAI_AIFM_Port_Probe

error_t MPAI_AIFM_Port_Probe(const char* port_name, message_t* message)

This function returns MPAI_AIF_OK if either the Port is a FIFO input port and an AIM can write to it, or the Port is a FIFO output Port and data is available to be read from it.

3.6.6 MPAI_AIFM_Port_Select

int MPAI_AIFM_Port_Output_Select(
const char* AIM_name_1,const char* port_name_1,…)

Given a list of output Ports, this function returns the index of one Port for which data has become available in the meantime. The call is blocking to address potential race conditions.

3.7 Operations on messages

All implementations shall provide a common Message passing functionality which is abstracted by the following functions.

3.7.1 MPAI_AIFM_Message_Copy

message_t* MPAI_AIFM_Message_Copy(message_t* message)

This function makes a copy of a Message structure message.

3.7.2 MPAI_AIFM_Message_Delete

message_t* MPAI_AIFM_Message_Delete(message_t* message)

This function deletes a Message message and its allocated memory. The format of each Message passing through a Channel is defined by the Metadata for that Channel.

3.7.3 MPAI_AIFM_Message_GetBuffer

void* MPAI_AIFM_Message_GetBuffer(message_t* message)

This function gets access to the low-level memory buffer associated with a message structure message.

3.7.4 MPAI_AIFM_Message_GetBufferLength

size_t MPAI_AIFM_Message_GetBufferLength(message_t* message)

This function gets the size in bits of the low-level memory buffer associated with a message structure message.

3.7.5 MPAI_AIFM_Message_Parse

parser_t* MPAI_AIFM_Message_Parse (const char* type)

This function creates a parsed representation of the data type defined in type according to the Metadata syntax defined in Subsection 6.1.1 Type system, to facilitate the successive parsing of raw memory buffers associated with message structures (see functions below).

3.7.6 MPAI_AIFM_Message_Parse_Get_StructField

void* MPAI_AIFM_Message_Parse_Get_StructField(
parser_t* parser, void* buffer, const char* field_name)

This function assumes that the low-level memory buffer buffer contains data of type struct_type whose complete parsed type definition (specified according to the metadata syntax defined in Subsection 6.1.1 Type system) can be found in parser. This function fetches the element of the struct_type named field_name, and return it in a freshly allocated low-level memory buffer. If a element with such name does not exist, return NULL.

3.7.7 MPAI_AIFM_Message_Parse_Get_VariantType

void* MPAI_AIFM_Message_Parse_Get_VariantType(
parser_t* parser, void* buffer, const char* type_name)

This function assumes that the low-level memory buffer buffer contains data of type variant_type whose complete parsed type definition (specified according to the Metadata syntax defined in Chapter 0, Type system) can be found in parser. Fetch the member of the variant_type named field_name, and return it in a freshly allocated low-level memory buffer. If a element with such name does not exist, return NULL.

3.7.8 MPAI_AIFM_Message_Parse_Get_ArrayLength

int MPAI_AIFM_Message_Parse_Get_ArrayLength(parser_t* parser, void* buffer)

This function assumes that the low-level memory buffer buffer contains data of type array_type whose complete parsed type definition (specified according to the Metadata syntax defined in Chapter Type system6.1.1, Type system) can be found in parser. Retrieve the length of such an array. If the buffer does not contain an array, return -1.

3.7.9 MPAI_AIFM_Message_Parse_Get_ArrayField

void* MPAI_AIFM_Message_Parse_Get_ArrayField(
parser_t* parser, void* buffer, const int field_num)

This function assumes that the low-level memory buffer buffer contains data of type array_type whose complete parsed type definition (specified according to the metadata syntax defined in Subsection 6.1.1, Type system) can be found in parser. Fetch the element of the array_type named field_num, and return it in a freshly allocated low-level memory buffer. If such element does not exist, return NULL.

3.7.10 MPAI_AIFM_Message_Parse_Delete

void MPAI_AIFM_Message_Parse_Delete(parser_t* parser)

This function deletes the parsed representation of a data type defined by parser, and deallocates all memory associated to it.

3.8 Functions specific to machine learning

The two key functionalities supported by the Framework are reliable update of AIMs with Machine Learning functionality and hooks for Explainability.

3.8.1 Support for model update

The following API supports AIM ML model update. Such update occurs via the Store by using the Store specific APIs or via Shared (SharedStorage) or AIM-specific (AIMStorage) storage by using the specified APIs.

error* MPAI_AIFM_Model_Update(const char* model_name)

The URI model_name points to the updated model. In some cases, such update needs to happen in highly available way so as not to impact the operation of the system. How this is effected is left to the Implementer.

3.8.2 Support for model drift

With this function the Controller detects possible degradation in ML operation caused by the characteristics of input data being significantly different from those used in training.

float MPAI_AIFM_Model_Drift(const char* name)

3.9 Controller API called by Controller

This Section specifies functions used by an AIM to Communicate through a Remote Port with an AIM running on another Controller. The local and remote AIMs shall belong to the same type of AIW.

3.9.1 MPAI_AIFM_External_List

error_t MPAI_AIFM_External_List(int* num_in_range, const char** controllers_metadata)

This function returns the number num_in_range of in-range Controllers with which it is possible to establish communication and running the same type of AIW, and a vector controllers_metadata containing AIW Metadata for each reachable Controller specified according to the JSON format defined in Section 6.3. In case more than one AIW of the same type is running on the same remote Controller, each such AIW is presented as a separate vector element.

3.9.2 MPAI_AIFM_External_Output_Read

message_t* MPAI_AIFM_External_Output_Read(int controllerID, const char* AIM_name, const char* port_name)

This function attempts to read a message from the External Port identified by (controllerID, AIM_name,port_name). The read is blocking. Hence, to avoid deadlocks, the Implementation should first probe the Port with MPAI_AIF_Port_Probe. It returns a copy of the original Message. This function attempts to establish a connection between the Controller and the external in-range Controller identified with a previous call to MPAI_AIFM_Communication_List. The call might fail due to the Controller not being in range anymore or other communication-related issues.

3.9.3 MPAI_AIFM_External_Input_Write

error_t MPAI_AIFM_External_Input_Write(int controllerID, const char* AIM_name, const char* port_name, message_t* message)

This function attempts to write a message message to the External Port identified by (controllerID, AIM_name, port_name). The write is blocking. Hence, in order to avoid deadlocks the Implementation should first probe the Port with MPAI_AIF_Port_Probe. The Message being transmitted shall remain available until the function returns, or the behaviour will be undefined. This function attempts to establish a connection between the Controller and the external in-range Controller identified with a previous call to MPAI_AIFM_Communication_List. The call might fail due to the Controller not being in range anymore or other communication-related issues.

<- Common API Features Go to ToC Security API ->

Cookie	Duration	Description
cookielawinfo-checkbox-necessary	1 year	This cookie is set by GDPR Cookie Consent plugin. The cookies is used to store the user consent for the cookies in the category "Technical".
CookieLawInfoConsent	1 year	The cookie is set by the GDPR Cookie Consent plug-in and is used to store whether the user has consented to the use of cookies or not. It does not store any personal data.
viewed_cookie_policy	1 year	The cookie is set by the GDPR Cookie Consent plugin and is used to store whether or not user has consented to the use of cookies. It does not store any personal data.
_pk_id.6.08a8	13 months	Used to store a few details about the user such as the unique visitor ID
_pk_ses.6.08a8	30 minutes	Short lived cookies used to temporarily store data for the visit

1 Store API called by Controller