Skip to main content
The actual work of calling the module runtime performs the module. This is because we use module runtimes as a way to provide a container for the module. Our Module Runtimes are therefore similar to build packs. They represent a Linux environment which contains a defined set of libraries (OS and Python). This means that we can provide a consistent environment for the module to run in.The module runtime is also responsible for the actual execution of the module. It is the module runtime that will call the module and pass the document to it. The contract between the module and Kodexa is basically defined by the module runtime.

​
How do Modules interact with the Module Runtime?

When you deploy a module into Kodexa you include the module runtime that you want to use. Today, all Kodexa module runtimes have the same interface, but this may change in the future. There are two primary forms of interaction between the module runtime and the module. The first is inference, the second is training. How the module runtime calls your module is based on how you have declared your module in the module.yml file.

​
Inference

The most common starting point with working with a module is learning how inference works. Let’s take a simple example of a module.yml: 
# A very simple first module that isn't trainable

slug: my-module
version: 1.0.0
orgSlug: kodexa
type: store
storeType: MODEL
name: My Module
metadata:
  atomic: true
  state: TRAINED
  moduleRuntimeRef: kodexa/base-module-runtime
  type: module
  contents:
    - module/*
The key thing to note here is the moduleRuntimeRef which is set to kodexa/base-module-runtime. This means that the Robotic Assistant will use the base module runtime to run the module. In fact, it will look up the module runtime with the ref kodexa/base-module-runtime. Then it will look at the module runtime to determine which action it uses for inference, and build a pipeline including that action. The platform will then schedule that pipeline and then module runtime action will be called. Module Runtimes When the module runtime is called it will be passed a document and also all the options that have been captured in the UI for the module. The module runtime will then look at the module.yml file and determine the entry point for the module. By default, the module runtime will expect a package called Module and then look for a function in that package called infer. The module runtime will pass the document that we are processing to the module and then the module will return a document. The module runtime will then pass the document back to the platform for further processing.

​
Inference with Options

In the previous example, we saw how the module runtime would pass the document to the module. In this example, we will see how the module runtime will pass options to the module. First, let’s add some inference options to our module.yml file: 
# A very simple first module that isn't trainable

slug: my-module
version: 1.0.0
orgSlug: kodexa
type: store
storeType: MODEL
name: My Module
metadata:
  atomic: true
  trainable: false
  moduleRuntimeRef: kodexa/base-module-runtime
  type: module
  inferenceOptions:
    - name: my_option
      type: string
      default: "Hello World"
      description: "A simple option"
  contents:
    - module/*
Here we can see we have added an inference option to the module.yml file. This option will be displayed in the UI when the module is used. The user can then change the value of the option and that value will be passed to the module runtime. When we deploy this module update, we now can use that new option in our inference code. 
import logging

logger = logging.getLogger(__name__)

def infer(document, my_option):
    logger.info(f"Hello from the module, the option is {my_option}")
    return document
As we can see, the option is passed to the module as a parameter.

​
Overriding Entry Points

If you want to override the entry point for your module, you can do so by specifying the moduleRuntimeParameters property in the module.yml file. 
moduleRuntimeParameters:
  module: my_module
  function: custom_infer
  training_function: custom_train

​
Magic Parameters for Training and Inference

When you are training or inferring a module, you can pass in some magic parameters to the module runtime. If you include a parameter in either your train or infer function, it will be passed in by the module runtime.
Parameter NameTrain/InferDescription
module_storeBothAn instance of the ModuleStoreEndpoint for the module you are using
module_dataBothA string representing the path where you in training you can store data and in inference you can pick it up
pipeline_contextBothThe PipelineContext for the processing pipeline
training_idBothThe ID of the ModuleTraining that is in use
additional_training_documentTrainA Document representing the document being tested
training_optionsTrainingA dictionary of the training options that have been set for the module

​
Inference Options

While in training we pass all the training options as a dictionary, in inference we pass the options as individual parameters. This is because we want to make it easy to use the options in the inference code. Therefore, if you have an inference option called my_option then you will get a parameter called my_option passed to your inference function. 
def infer(document, my_option):
    logger.info(f"Hello from the module, the option is {my_option}")
    return document