Skip to main content
Module runtimes provide the execution environment for Kodexa modules. They package the Linux and Python dependencies needed to run your code consistently across Lambda and Kubernetes-based execution. The runtime is responsible for downloading your module, importing the correct package, injecting execution context, and returning the processed document back to the platform. In practice, the runtime defines the contract between your module code and Kodexa.

​
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. 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

slug: my-module
version: 1.0.0
orgSlug: kodexa
type: store
storeType: MODEL
name: My Module
metadata:
  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. The platform resolves that runtime, provisions the correct execution environment, and uses it to run the module during assistant executions. Module Runtimes When the module runtime is called, it receives the document plus the inference options configured for that step. By convention most modules package their Python code under module/, and the runtime calls infer from that package. If your archive contains multiple Python packages, the runtime can be told which package to import by setting metadata.modelRuntimeParameters.module. 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

slug: my-module
version: 1.0.0
orgSlug: kodexa
type: store
storeType: MODEL
name: My Module
metadata:
  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.

​
Targeting a Specific Package

If your module ZIP contains more than one Python package, set metadata.modelRuntimeParameters.module so the bridge imports the correct package: 
metadata:
  modelRuntimeParameters:
    module: my_module
The runtime still calls infer by default. For event-aware modules it falls back to handle_event when that function is present.

​
Magic Parameter Injection

When a module function is called by the Kodexa bridge, parameters are automatically injected based on the function signature. You only need to declare the parameters you want — the bridge inspects your function signature and passes matching values automatically.

​
Available Parameters

ParameterTypeDescription
documentDocumentThe Kodexa document being processed (inference only)
model_basestrPath to the model’s base directory on disk
pipeline_contextPipelineContextThe pipeline execution context
module_refstrReference to the module being executed
module_optionsdictModule-level configuration options
assistantAssistantThe assistant associated with this execution
assistant_idstrThe assistant ID
projectProjectThe project this execution belongs to
execution_idstrThe current execution ID
status_reporterStatusReporterHelper for posting live status updates to the UI
pipeline_context is the main entry point for execution metadata. It exposes:
  • pipeline_context.document_family
  • pipeline_context.content_object
  • pipeline_context.document_store
  • pipeline_context.context for the raw event/context payload

​
Usage

Declare only the parameters your function needs: 
def infer(document, pipeline_context=None, model_base=None):
    # Only document, pipeline_context, and model_base are injected
    ...

​
Inference Options

In addition to the magic parameters above, any inference options declared in your module.yml are also injected by name. 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

​
StatusReporter

The status_reporter parameter provides fire-and-forget status updates that appear in the UI during execution. All calls are safe — errors are logged but never propagated. 
status_reporter.update(title, subtitle=None, status_type="processing")
ArgumentRequiredDescription
titleYesPrimary status message
subtitleNoSecondary detail text
status_typeNoOne of: thinking, searching, planning, reviewing, processing, analyzing, writing, waiting
Updates are rate-limited to one per second. 
def infer(document, status_reporter=None, model_base=None):
    if status_reporter:
        status_reporter.update("Extracting tables", status_type="processing")

    # ... do work ...

    if status_reporter:
        status_reporter.update("Running classification",
                               subtitle="Page 3 of 12",
                               status_type="analyzing")

    # ... more work ...
    return document

​
Available Runtimes

Kodexa provides several built-in module runtimes for different processing needs:
RuntimeSlugDescription
Base Module Runtimekodexa/base-module-runtimeStandard Python runtime for custom modules
Go Scripting Runtimekodexa/go-scripting-runtimeLightweight runtime for inline JavaScript modules
Cloud Model Runtimekodexa/cloud-model-runtimeRuntime for cloud-hosted AI models
Excel Runtimekodexa/excel-runtimeExcel/spreadsheet document processing
Azure Runtimekodexa/azure-runtimeAzure Form Recognizer integration
Textract Runtimekodexa/textract-runtimeAWS Textract integration
Google Runtimekodexa/google-runtimeGoogle Document AI integration
UNO Runtimekodexa/uno-runtimeOffice document conversion via LibreOffice/UNO (Word, Excel, PowerPoint)
Agent Model Runtimekodexa/agent-model-runtimeRuntime for agentic AI processing

​
Pipeline Context Status Handler

For step-level progress tracking (progress bars in the UI), use the pipeline_context.status_handler callback: 
def infer(document, pipeline_context=None):
    pages = document.get_nodes()
    for i, page in enumerate(pages):
        pipeline_context.status_handler(
            f"Processing page {i+1}",  # message
            i + 1,                      # progress
            len(pages)                  # progress_max
        )
        # ... process page ...
    return document