Skip to content

Add Python examples for KNI usage #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bruno-at-orange wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add Python examples for KNI usage #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b23b906
Add Python examples for KNI usage
bruno-at-orange May 11, 2026
47b6876
After review
bruno-at-orange May 12, 2026
e352da5
Refactor Python API to use exceptions instead of return codes
bruno-at-orange May 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1,2 @@
.vscode/
python/__pycache__/
92 changes: 80 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@

# Khiops Native Interface v11.0.0
# Khiops Native Interface v11.0.1-a.5

This project provides all the basics to use the Khiops Native Interface (KNI): installation and examples.

The purpose of KNI is to allow a deeper integration of Khiops in information systems, by mean of the C programming language, using a shared library (`.dll` in Windows, `.so` in Linux). This relates specially to the problem of model deployment, which otherwise requires the use of input and output data files when using directly the Khiops tool in batch mode. See Khiops Guide for an introduction to dictionary files, dictionaries, database files and deployment.
The purpose of KNI is to allow a deeper integration of Khiops in information systems, by means of the C programming language, using a shared library (`.dll` in Windows, `.so` in Linux). This relates especially to the problem of model deployment, which otherwise requires the use of input and output data files when using directly the Khiops tool in batch mode. See Khiops Guide for an introduction to dictionary files, dictionaries, database files and deployment.

The Khiops deployment API is thus made public through a shared library. Therefore, a Khiops model can be deployed directly from any programming language, such as C, C++, Java, Python, Matlab, etc. This enables real time model deployment without the overhead of temporary data files or launching executables. This is critical for certain applications, such as marketing or targeted advertising on the web..
The Khiops deployment API is thus made public through a shared library. Therefore, a Khiops model can be deployed directly from any programming language, such as C, C++, Java, Python, Matlab, etc. This enables real-time model deployment without the overhead of temporary data files or launching executables. This is critical for certain applications, such as marketing or targeted advertising on the web.
Copy link
Copy Markdown

@popescu-v popescu-v May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd state somewhere that the API is compatible with ISO C99 (or the applicable standard if different, e.g. ANSI / ISO C89).

Copy link
Copy Markdown
Member Author

@bruno-at-orange bruno-at-orange May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done


All KNI functions are C functions for easy use with other programming languages. They return a positive or zero value in case of success, and a negative error code in case of failure.

Expand All @@ -14,15 +14,32 @@ See [KhiopsNativeInterface.h](include/KhiopsNativeInterface.h) for a detailed de
> [!CAUTION]
> The functions are not reentrant (thread-safe): the library can be used simultaneously by several executables, but not simultaneously by several threads in the same executable.
Copy link
Copy Markdown

@popescu-v popescu-v May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we suggest using multiprocessing e.g. via MPI if parallelization is needed?

Copy link
Copy Markdown
Member Author

@bruno-at-orange bruno-at-orange May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think It's not necessary


## Table of Contents

- [KNI installation](#kni-installation)
- [Windows](#windows)
- [Linux](#linux)
- [Application examples](#application-examples)
- [Example with C](#example-with-c)
- [Building the examples](#building-the-examples)
- [Launch](#launch)
- [Example with Java](#example-with-java)
- [Building the examples](#building-the-examples-1)
- [Launch](#launch-1)
- [Example with Python](#example-with-python)
- [Requirements](#requirements)
- [Scripts](#scripts)
- [Launch](#launch-2)

# KNI installation

## Windows

Download [KNI-11.0.0.zip](https://github.com/KhiopsML/khiops/releases/tag/11.0.0/KNI-11.0.0.zip) and extract it to your machine. Set the environment variable `KNI_HOME` to the extracted directory. This variable is used in the following examples.
Download [KNI-11.0.1-a.5.zip](https://github.com/KhiopsML/khiops/releases/tag/11.0.1/KNI-11.0.1-a.5.zip) and extract it to your machine. Set the environment variable `KNI_HOME` to the extracted directory. This variable is used in the following examples.

## Linux

On Linux, go to the [release page](https://github.com/KhiopsML/khiops/releases/tag/11.0.0/) and download the KNI package. The name of the package begins with **kni** and ends with the **code name** of the OS. The code name is in the release file of the distribution (here, it is "jammy"):
On Linux, go to the [release page](https://github.com/KhiopsML/khiops/releases/tag/11.0.1/) and download the KNI package. The name of the package begins with **kni** and ends with the **code name** of the OS. The code name is in the release file of the distribution (here, it is "jammy"):
```bash
$ cat /etc/os-release
PRETTY_NAME="Ubuntu 22.04.4 LTS"
Expand All @@ -46,7 +63,7 @@ Download the package according to the code name of your OS and install it with `

Application examples are available in this repository. The main branch corresponds to the latest version of KNI. To explore older versions, switch between branches, which are named after their respective versions.

Both examples in C and Java produce a sample binary `KNIRecodeFile`. It recodes an input file to an output file, using a Khiops dictionary from a dictionary file.
Examples in C, Java, and Python demonstrate how to use KNI. The main example, `KNIRecodeFile`, recodes an input file to an output file using a Khiops dictionary from a dictionary file.

```bash
KNIRecodeFile <Dictionary file> <Dictionary> <Input File> <Output File> [Error file]
Expand All @@ -55,14 +72,14 @@ KNIRecodeFile <Dictionary file> <Dictionary> <Input File> <Output File> [Error f
# The error file may be useful for debugging purposes. It is optional and may be empty.
```

A more complex example (available only in C) is `KNIRecodeMTFiles`, it recodes the input files of multi-table dataset to a single output file.
A more complex example (available in C and Python) is `KNIRecodeMTFiles`, which recodes the input files of a multi-table dataset to a single output file.

```bash
KNIRecodeMTFiles
-d: <input dictionary file> <input dictionary>
[-f: <field separator>
-i: <input file name> [<key index>...]
-s: <secondary data path> < file name> <key index>...
-s: <secondary data path> <file name> <key index>...
-x: <external data root> <external data path> <external file name>
-o: <output file name>
[-e: <error file name>]
Expand All @@ -71,7 +88,7 @@ KNIRecodeMTFiles

# Example with C

The files are located in [cpp directory](cpp/). They allow to build `KNIRecodeFile` and `KNIRecodeMTFiles`.
The files are located in [cpp directory](cpp/). They allow you to build `KNIRecodeFile` and `KNIRecodeMTFiles`.

## Building the examples

Expand Down Expand Up @@ -103,12 +120,12 @@ Recode the "Splice Junction" multi-table dataset using the `SNB_SpliceJunction`

```bash
KNIRecodeMTFiles -d data/ModelingSpliceJunction.kdic SNB_SpliceJunction \
-i .data/SpliceJunction.txt 1 -s DNA data/SpliceJunctionDNA.txt 1 -o R_SpliceJunction.txt
-i data/SpliceJunction.txt 1 -s DNA data/SpliceJunctionDNA.txt 1 -o R_SpliceJunction.txt
```

# Example with Java

The files are located in [java directory](java/). They allow to build `KNIRecodeFile.jar`. This example use [JNA](https://github.com/twall/jna#readme) to make calls to KhiopsNativeInterface.so/dll from Java.
The files are located in [java directory](java/). They allow you to build `KNIRecodeFile.jar`. This example uses [JNA](https://github.com/twall/jna#readme) to make calls to KhiopsNativeInterface.so/dll from Java.

## Building the examples

Expand All @@ -122,7 +139,7 @@ jar cf kni.jar -C java KNI.class -C java KNIRecodeFile.class

## Launch

Recodes the "Iris" dataset from the data directory using the `SNB_Iris` classifier dictionary.
Recode the "Iris" dataset from the data directory using the `SNB_Iris` classifier dictionary.

On Linux:

Expand All @@ -138,3 +155,54 @@ set path=%KNI_HOME%/bin;%path%
java -cp kni.jar;jna.jar KNIRecodeFile data/ModelingIris.kdic SNB_Iris ^
data/Iris.txt R_Iris_java.txt
```

# Example with Python

The files are located in [python directory](python/). They use Python's `ctypes` to call the KhiopsNativeInterface shared library directly.

## Requirements

- Python 3.6 or later
Copy link
Copy Markdown

@popescu-v popescu-v May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd start with the earliest still supported version of Python, viz. 3.10 currently.

Copy link
Copy Markdown
Member Author

@bruno-at-orange bruno-at-orange May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

- The KNI shared library must be installed and accessible (via `KNI_HOME` environment variable or standard system paths)

## Scripts

- `KNI.py`: Python wrapper for KhiopsNativeInterface using ctypes
- `KNIRecodeFile.py`: Single-table recoding example
- `KNIRecodeMTFiles.py`: Multi-table recoding example

## Launch

Recode the "Iris" dataset from the data directory using the `SNB_Iris` classifier dictionary.

On Linux:

```bash
python3 python/KNIRecodeFile.py data/ModelingIris.kdic SNB_Iris \
data/Iris.txt R_Iris_python.txt
```

On Windows:

```cmd
set path=%KNI_HOME%/bin;%path%
python python\KNIRecodeFile.py data/ModelingIris.kdic SNB_Iris ^
data/Iris.txt R_Iris_python.txt
```

For the multi-table "Splice Junction" example:

On Linux:

```bash
python3 python/KNIRecodeMTFiles.py -d data/ModelingSpliceJunction.kdic SNB_SpliceJunction \
-i data/SpliceJunction.txt 1 -s DNA data/SpliceJunctionDNA.txt 1 -o R_SpliceJunction_python.txt
```

On Windows:

```cmd
set path=%KNI_HOME%/bin;%path%
python python\KNIRecodeMTFiles.py -d data/ModelingSpliceJunction.kdic SNB_SpliceJunction ^
-i data/SpliceJunction.txt 1 -s DNA data/SpliceJunctionDNA.txt 1 -o R_SpliceJunction_python.txt
```
Loading