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 Altair AI Tools.

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
environment	Python environment ID (`key:version`)	string
module	name of the module containing the operator functions	string

The Python environment ID consists of the key and an optional version of the Python distribution required to execute the contained Python code. Alternatively, 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.

For example, these are valid environment IDs:

sample-environment
sample-environment:0.1.0
or for dependency-based environments 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	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	-
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.
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"
environment = "sample-environment: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.

In the next section, take a look at next concept i.e. Python Environments in the Python extensions.

Categories

Versions