.. _nrf_edgeai_lib_runtime:

nRF Edge AI runtime module
##########################

.. contents::
   :local:
   :depth: 2

The nRF Edge AI Runtime library module provides a lightweight C library with interface for initializing and running machine learning models generated by the `Nordic Edge AI Lab`_ web tooling.

Overview
********

The runtime handles model setup, input feeding, inference execution, and output decoding.
Models are generated using the `Nordic Edge AI Lab`_ web tooling and distributed as C source files that integrate with the |NCS| build system.
For more information about integrating Nordic Edge AI Lab models, see :ref:`ug_nrf_edgeai_integration`.
This model provides the following features:

* Sets up model parameters and allocates necessary resources.
* Accepts raw input data (sensor readings, signal samples) and prepares it for inference.
* Runs the model's inference pipeline to generate predictions.
* Extracts and interprets model outputs for application use.

The runtime is designed to be portable and efficient, making it suitable for deployment on Nordic Semiconductor devices with constrained resources.
It abstracts the complexities of model execution, allowing you to focus on application logic rather than low-level model handling.

Module structure
****************

The runtime module (:file:`include/nrf_edgeai/rt/`) is organized into several header files, each responsible for a specific part of the API or data structure:

* :file:`nrf_edgeai_runtime.h` - Core runtime API (init, feed inputs, run inference)
* :file:`nrf_edgeai_types.h` - Type definitions (context, interfaces, metadata)
* :file:`nrf_edgeai_input_types.h` - Input handling types and structures
* :file:`nrf_edgeai_model_types.h` - Model definitions and output structures
* :file:`nrf_edgeai_output_types.h` - Classification, regression, and anomaly output types
* :file:`nrf_edgeai_dsp_pipeline_types.h` - DSP pipeline configuration

Core API
********

The runtime API consists of a small number of essential functions for model inference:

* Initialization and inference

  * :c:func:`nrf_edgeai_init` - Initializes the runtime (call once at startup).
  * :c:func:`nrf_edgeai_feed_inputs` - Feeds raw input data (sensor readings, signal samples) to the model.
  * :c:func:`nrf_edgeai_run_inference` - Executes the model inference pipeline, including features processing and compute predictions.

* Input information

  * :c:func:`nrf_edgeai_input_type` - Gets the data type of input features (for example, int16, float32).
  * :c:func:`nrf_edgeai_uniq_inputs_num` - Gets the number of unique input features the model expects.
  * :c:func:`nrf_edgeai_input_window_size` - Gets the size of the input window (for time-series models).
  * :c:func:`nrf_edgeai_input_subwindows_num` - Gets the number of subwindows in the input.

* Model information

  * :c:func:`nrf_edgeai_model_neurons_num` - Gets the number of neurons in the model.
  * :c:func:`nrf_edgeai_model_weights_num` - Gets the number of weights in the model.
  * :c:func:`nrf_edgeai_model_outputs_num` - Gets the number of model outputs.
  * :c:func:`nrf_edgeai_model_task` - Gets the model task type (classification, regression, anomaly detection).

* Solution and version information

  * :c:func:`nrf_edgeai_solution_id_str` - Gets the solution ID string.
  * :c:func:`nrf_edgeai_solution_runtime_version` - Gets the version of the solution runtime.
  * :c:func:`nrf_edgeai_runtime_version` - Gets the version of the Edge AI library runtime.
  * :c:func:`nrf_edgeai_is_runtime_compatible` - Checks version compatibility between library and solution.

* Output access - After a successful :c:func:`nrf_edgeai_run_inference`, results are available through the ``decoded_output`` member of the context:

  * ``p_edgeai->decoded_output.classif`` — Classification results (predicted class, probabilities, number of classes)
  * ``p_edgeai->decoded_output.regression`` — Regression results (predicted values array, number of outputs)
  * ``p_edgeai->decoded_output.anomaly`` — Anomaly detection results (anomaly score)

* Model task types supported - The :c:type:`nrf_edgeai_model_task_t` enum specifies the model's task.

  * ``NRF_EDGEAI_TASK_MULT_CLASS`` — Multi-class classification
  * ``NRF_EDGEAI_TASK_BIN_CLASS`` — Binary classification
  * ``NRF_EDGEAI_TASK_REGRESSION`` — Regression (numeric prediction)
  * ``NRF_EDGEAI_TASK_ANOMALY`` — Anomaly detection

* Input types supported - Models accept input data of type :c:type:`nrf_edgeai_input_type_t`.

  * ``NRF_EDGEAI_INPUT_I8`` — 8-bit signed integer
  * ``NRF_EDGEAI_INPUT_I16`` — 16-bit signed integer
  * ``NRF_EDGEAI_INPUT_F32`` — 32-bit floating-point

Example worklflow
*****************

The general integration sequence involves initializing the model, feeding input data, running inference, and accessing the results.
The following example demonstrates this workflow:

.. include:: ../../../includes/include_edgeai_rt_basic_integration_example.txt