MPAI-AIF V3.0 – AI Modules

<-User Agent Go to ToC Controller ->

1 Reference Model

Figure 1 depicts the Reference Model of an AI Module (AIM).

Figure 1 – Reference Model of an AIM

An AIM is a processing element that receives data at its Input Ports and produces data at its Output Ports according to its Function. It is described by its Metadata and has four interfaces, listed in Table 1.

Table 1 – Interfaces of an AIM

Interface	Between	Function
AIM interface	The AIM and other AIMs, or the boundary of the Module	Objects cross the AIM’s Ports over the Channels the Controller establishes (Communication). The AIM neither sees nor chooses the AIMs at the other end.
Controller interface	The AIM and the Controller	The Controller API, AIM face (Basic API): read and write the AIM’s own Ports, with a timeout; select among Ports with pending Messages; read the time; report; where allowed, request life-cycle changes of other AIMs and use External Ports. The Controller starts, pauses, resumes and stops the AIM.
Trust interface	The AIM and the Controller, as trust authority of the Module	The AIM presents its identity and credentials and the attestation of what it runs – the fingerprint of its Implementation, which the MPAI Store approved – and receives its admission; where allowed, it has what it produces signed. In the Secure Profile this interface reaches the secure part of the Controller. For an AIM on another machine, the AIM host carries it by the Trust Protocol (Zero Trust and Profiles). It is distinct from the Security API, which provides cryptographic services to an AIM.
Private Storage interface	The AIM and its Private Storage	Read and write data that the AIM keeps across executions, under the rules of the data (Storage). The Private Storage of an AIM is reached by that AIM alone.

2 The AIM hierarchy

Figure 2 depicts how AIMs are organised.

Figure 2 – The AIM hierarchy

Table 2 – Levels of the AIM hierarchy

Level	Definition
Middleware	The pool of AIM Implementations from which Modules are made, obtained from the MPAI Store or held locally, each described by its Metadata. The Middleware is not the Controller and exposes no interface of its own.
Module	The AIM a Controller runs: one Controller, one Module. A Module is Basic, or Composite. It is selected from the Middleware and connected as the Topology of its Metadata states (6).
Composite AIM	An AIM made of Sub-AIMs connected by a Topology (5).
Sub-AIM	An AIM inside a Composite AIM. A Sub-AIM is Basic, or Composite, and a Composite Sub-AIM has Sub-AIMs of its own, to any depth. A Composite inside a Module is a Sub-AIM, never a Module.
Basic AIM	An AIM with no Sub-AIMs. Every branch of the hierarchy ends in Basic AIMs.

Every AIM of the hierarchy has the Reference Model of Figure 1. A Composite AIM is seen from outside exactly as a Basic AIM is: by its Ports and its Function.

3 AIMs

An AIM consumes and produces Objects. It neither acquires data from the real world nor delivers data to it: that is the Physical Layer of the User Agent.

Data crosses a Port as an Object: data with a Qualifier stating what the data is – format, sampling frequency, precision, language, object type. A consumer reads the Qualifier; it does not inspect the data to find out. An Object cannot be constructed without a Qualifier.

An AIM keeps no state of an interaction between executions. State that must persist – a conversation’s memory, for instance – travels as data through the boundary or is kept in Storage. This is what allows one Implementation of an AIM to serve several Modules and several clients.

An AIM may run in the Controller’s process, in another process on the same machine, or on another machine (7). Where it runs does not change what it is.

4 Ports

A Port is addressed by its Data Type and its Port Number, never by its name. Where an AIM declares one Port of a Direction and Data Type, its Metadata omits the Port Number, and the Port Number is 1. A Port name is a label for the reader of the Metadata: it is dropped when the Metadata is ingested and never routes data.

A Port carries an MPAI Data Type or a type of the type system of MPAI-AIF (Metadata). A Port may accept a set of Data Types – a Basic and a full Object, for example. A value carries its own Header, so the receiving AIM knows which it was given. A Port may declare its behaviour when full or when data are old (Communication), whether it is optional, and the transports it accepts.

Four numberings apply, none derived from another (Table 3).

Table 3 – Numberings of Ports

Numbering	Scope	Declared by	Disambiguates
Port Number (within an AIM)	One AIM’s own Ports	That AIM’s Metadata	Ports of one Direction and Data Type in one AIM
Port Number (Composite pool)	A Composite’s boundary and the Sub-AIM Ports its Topology names	The Composite’s Metadata	Ports of one Direction and Data Type in that pool
Output	One edge from a parent into a child Composite	The parent, on the Port or Internal Type from which the edge leaves	Which of the child’s Input groups the flow feeds
Input	A child Composite’s same-typed Port group	The child’s External Ports	Which external supply the group receives

5 Composite AIMs

A Composite AIM is an aggregation of Sub-AIMs connected by a Topology. Each end of a Topology line is named by a label of the Composite itself – one of its External Ports or Internal Types – which gives the Data Type. The name a Sub-AIM gives its own Port is never read, and a Topology using a label the Composite does not declare does not load. The Controller resolves the Topology once, at load time, into connections of Data Type and Port Number.

A Composite AIM needs no Implementation package: it is a graph the Controller builds from its Sub-AIMs. How it is executed – by exchange or continuously – is declared in its Metadata (Execution).

6 Modules

A Module is an instantiation of the Metadata of an AIM Instance. One Controller runs one Module, and one User Agent drives it.

A Module is identified by the Identifier of an AIM Instance – Implementer ID and Implementation ID together, for example 1MMC-AMQ-V2.5-I01 – not by the AIM name a Standard specifies. The same holds for every AIM its Metadata names: Metadata naming a Standard AIM describes a Module in principle and leaves open which Implementation realises it.

A Composite Module has a Private Storage, reached by its own AIMs, by the Controller on its behalf and by the User Agent that drives it, each as the rules of the data allow. A Module may have External Ports, through which it exchanges data with Modules run by other Controllers.

The boundary Ports of a Module are the only points at which a User Agent reaches it. A Module intended to be driven by a User Agent meets two conditions:

• Sufficiency: every boundary Port is identifiable by Data Type, or by Data Type and Port Number.
• Completeness: the boundary carries every datum a User Agent is to give or to obtain. What the boundary does not carry, the User Agent cannot reach, and shall not try to.

It follows that a Module declares a distinct Port for each purpose a Data Type serves – for example, one Text Port for words to be spoken and another for a question in writing. Nothing infers a purpose from which inputs happen to be absent.

7 Placement

Where a Sub-AIM runs is stated by its Relation in the Metadata of the Composite that contains it (Table 4).

Table 4 – Relations of a Sub-AIM

Relation	Where the Sub-AIM runs	Used by
Internal	On the machine provisioned for the containing AIM Instance (the default)	That instance only
External	On its own machine	That instance only
Private	On its own machine, a service instance named by Host	AIM Instances of the same provisioning account
Public	On its own machine, a service instance named by Host	Any AIM Instance

The Relation is written by the developer of the Metadata, or changed at deployment time by whoever deploys the Module. The Relation says that a Sub-AIM runs elsewhere; the Controller’s configuration says where. A Sub-AIM that is not Internal and for which no host is named refuses the Module, and the Controller says why.

A Sub-AIM placed elsewhere remains an AIM of the one Module, under the one Controller. On another machine it is instantiated by an AIM host: a program that, on the Controller’s orders, instantiates an AIM, runs, pauses, resumes and stops it, and reports its status. An AIM host runs no graph, decides nothing and keeps no Module. A Composite Sub-AIM that is not Internal has all its AIMs on its host; the Controller still runs its graph, and only the Channels that cross to the host change transport.

8 Reports and status

An AIM may report, to whoever operates the AIF, something it did or could not do – a resource absent and substituted for, an input accepted with a reduced interpretation. A report is not an error, and the Controller conveys it without acting on it.

An AIM is ALIVE, DEGRADED or DEAD. It is DEGRADED while it runs on less than it was designed to. What a Module does when one of its AIMs degrades is its policy, declared in its Metadata and applied by the Controller.

9 Metadata

An AIM is described by Metadata of three kinds (Metadata):

• AIM Metadata Schema: the JSON Schema against which AIM Metadata and AIM Instance Metadata validate.
• AIM Metadata: describes an AIM as a Standard specifies it, identified by the AIM type (e.g., MMC-EDP-V2.5): Function, Ports and, for a Composite AIM, its Sub-AIMs and Topology.
• AIM Instance Metadata: describes one AIM Instance, identified by its AIM Instance Identifier (e.g., 1MMC-EDP-V2.5-I01): its Implementations, Relation, resources and the values the AIM Metadata leaves open. It declares only what its Implementation supports, and is an instance of the AIM Metadata its Header names.

The Metadata of a Module is the AIM Instance Metadata of the AIM the Controller runs.

10 Implementations

10.1 Implementation types

AIMs can be implemented in hardware or software keeping the same interfaces, independent of the implementation technology. However, the nature of an AIM may impose constraints on the values of certain API parameters, and different Profiles may impose different constraints.

While software-software and hardware-hardware connections are homogeneous, a hybrid hardware-software connection is heterogeneous and requires additional communication protocols, which wrap the hardware part and connect it to software. A list of such protocols is provided by the MPAI Ontology.

Examples of supported architectures are:

• CPU-based devices running an operating system.
• Memory-mapped devices (FPGAs, GPUs, TPUs) presented as accelerators.
• Cloud-based frameworks.
• Naked hardware devices (i.e., IP in FPGAs) that communicate through hardware Ports.
• Encapsulated blocks of a hardware design (i.e., IP in FPGAs) that communicate through a memory-mapped bus. In this case, the Metadata of the AIM shall also specify the low-level communication protocol used by the Ports.

10.2 Combination

MPAI-AIF supports the following ways of combining AIMs:

• Software AIMs connected to other software AIMs, resulting in a software AIM.
• Non-encapsulated hardware blocks connected to other non-encapsulated hardware blocks, resulting in a larger non-encapsulated hardware AIM.
• Encapsulated hardware blocks connected to other encapsulated hardware blocks or to software blocks, resulting in a larger software AIM.

Connection between a non-encapsulated hardware AIM and a software AIM is not supported, as direct communication between them cannot be defined in any meaningful way.

10.3 Hardware-software compatibility

To achieve communication among AIMs irrespective of their implementation technology:

1. Hardware AIM to hardware AIM: each named type in a Structure is transmitted as a separate Channel. Vector types are implemented as two Channels, one transmitting the size and the other the data.
2. All other combinations: a Structure is filled by recursively traversing its definition (breadth-first). Sub-fields are laid down according to their type, in little-endian order.

10.4 Actual implementations

Hardware. Metadata ensures that hardware blocks can be directly connected to other hardware or software blocks, provided the two blocks have compatible interfaces, i.e., compatible Ports and Channels.

Software. A software Implementation is the build output of an AIM for one architecture and operating system – a package – at the address its AIM Instance Metadata names. A model an AIM needs is named by its settings and may be obtained from the party that publishes it, checked against the hash its settings state. A software Implementation:

1. reads and writes its own Ports, and only those, through the Controller API;
2. declares its Ports in its Metadata, and does not register Ports or Channels at run time: the Controller builds them from the Metadata;
3. may add arbitrary functionality – for example, libraries managing a GPU or an FPGA through Direct Memory Access, or high-level libraries implementing AI functionality;
4. uses an implementation of the API that depends on the architecture it is designed for.

11 Requirements

Table 5 – Requirements of an AIM

#	Requirement
AIM-1	An AIM shall address data by the Data Type and Port Number of its own Ports, never by a Port name and never by another AIM.
AIM-2	An AIM shall deal with the Controller only through the Controller API, and shall not open a Channel of its own.
AIM-3	An AIM shall produce every datum as an Object with its Qualifier.
AIM-4	An AIM shall keep no state of an interaction between executions except in Storage.
AIM-5	An AIM shall neither acquire data from the real world nor deliver data to it.
AIM-6	The Implementation of an AIM shall support what its AIM Instance Metadata declares, and its AIM Instance Metadata shall be an instance of its AIM Metadata.
AIM-7	An AIM shall run only after the Controller has verified it through the Trust interface.

<-User Agent Go to ToC Controller ->