<- API Conventions Go to ToC Security API ->
1 Store API called by Controller
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.
The Controller implements the functions relative to the file retrieval as described in 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. 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.
