Configure the extension

Extension configuration defines your extension by detailing its properties, available operators, dependencies, and environments. The configuration is stored in the extension.toml file, which the build script uses to package your extension for the Rapidminer AI suite.

The configuration file: extension.toml

The extension can be configured using the extension.toml file. By default, the build script looks for the configuration file at PATH/extension.toml. However, this path can be specified using the -f or --file command line argument.

Mandatory attributes

There are some attributes that must be specified in the configuration file in the scope [extension]:

Key	Description	Type
name	display name of the extension	string
namespace	namespace of the extension	string
version	version of the extension	string
module	name of the module containing the operator functions	string

The name attribute specifies how the extension appears in the operator list within AI product suite. The namespace and version attributes uniquely identify the extension. The module attribute refers to the root-level folder containing the operator code, which must include an __init__.py file to be recognized as a Python module.

In most cases the environment name is automatically generated based on the extension's dependencies, and this behaviour cannot be overridden, as this avoids environment name collisions. One exception to this is when the extension depends on another extension, in which case the environment name of the dependency can be specified explicitly.

The environment of an extension dependency (see below for details) can be specified using the syntax dep::NAMESPACE_OF_DEPENDENCY. When this syntax is used, the active environment is not resolved, and downloading packages for offline environment creation is disabled. Therefore, it is the developer's responsibility to ensure the environment's validity, preferably by building the extension using the specified environment. Specifying the environment name otherwise is ignored, and will have no effect whatsoever.

This is a valid environment ID for a dependent extension's environment: dep::sample-dependency-extension.

Optional attributes

In addition to the mandatory attributes, extension developers are allowed to specify the following configuration properties in the [extension] scope:

Key	Description	Type
min_core_version	minimum version of AI Studio Core	string
license	license identifier (see below for details)	string
environment	optional environment specification for dependent envs	string
vendor	name of the vendor/author of the extension	string

Override operator attributes

The configuration file can be used to override the following attributes for each operator in the scope [operators.operator_name]:

Key	Description	Type	Default	Constraints
name	display name of the operator	string	titled name of the function	-
icon	id of the desired icon	string	null	-
color	hex string of the desired color	string	null	-
outputs	name of the output ports	list of strings	result{i} where is i is the port index	the length of the list must match with the number of ports
group_key	key of container group	string	null	allowed characters: [a-zA-Z0-9_.]; not allowed: whitespaces, two or more . directly next to each other, ending or starting with a .

Important Notes:

While in the configuration file namespace is used to define dependence, code can only be imported using the module attribute of the extension. (However, the two values can be the same.)
Only import objects from the configured dependencies directly, not from their dependencies (Those must also be explicitly configured).

Dependencies

Functionality can be imported from other Python extensions. First of all, it has to be specified which extension(s) to depend on. This can be done by defining the list of extensions and their minimum version in the configuration file extension.toml under the extension.dependencies scope:

[extension]
name = "Dependent Extension"
namespace = "depex"
version = "0.1.0"
module = "depex"

[extension.dependencies]
pytensors = "0.3.0"

The extension archives of the extensions listed here must be included in the dependencies folder:

depex/
├── extension.toml
├── depex
│   ├── __init__.py
│   └── operator.py
└── dependencies
    └──  pytensors-0.3.0.zip

Finally, Python's importing system can be used to import objects from other extensions:

from pandas import DataFrame
import tensors

def sample_random_data(rows: int = 5, cols: int = 2) -> DataFrame:
    return tensors.tensor_to_df(tensors.random_tensor(rows, cols))

Note: In the above example tensors is the main module of pytensors.

Error Messages

The SDK provides a convenient way to raise UserErrors in Python operators, which are displayed in the GUI with formatted and internationalized messages. Each error is identified by a unique error ID, and developers can define titles, short descriptions, and long descriptions for these errors in resource files located under resources/i18n/ as errors*.properties. For each error ID, at least a short description must be provided; default values will be used for any missing attributes.

Example resources/i18n/errors.properties:

error_id_1.name = Error 1
error_id_1.short = Error 1 Short with args: {0}, {1}
error_id_1.long = Error 1 Long description...

error_id_2.short = Error 2 Short with arg {0}, using defaults for name and long

Note: You can provide localized error messages by creating additional files such as errors_ja.properties. All properties files must be UTF-8 encoded.

In Python operators, raise an instance of altair_aitools.ext.errors.UserError with the error ID and any formatting arguments to trigger this mechanism.

Example

from rapidminer.ai.ext.errors import UserError

def throw_user_error() -> None:
    raise UserError("error_id_1", "arg_1", "arg_2")

Next, we will learn about building Python extensions.

Categories

Versions