Create Plugins#

This how-to explains how to build Plugins in Dioptra. You will learn how to create a plugin container, add code to it, and register tasks.

Prerequisites#

Prepare Your Deployment - A deployment of Dioptra is required.
Set Up Dioptra in the GUI - Access Dioptra services in the GUI, create a user, and login.

Plugin Creation Workflow#

Follow these steps to create and register a new plugin. You can perform these actions via the Guided User Interface (GUI) or programmatically using the Python Client.

Step 1: Prepare your Python Code#

Write your Python functions or Artifact classes in a local file. Ensure you have applied the necessary decorators or class inheritance.

For standard functions, see Function Tasks Reference.
For artifact handlers, see Artifact Tasks Reference.

Step 2: Create the Plugin Container#

First, define the container that will hold your files.

In the Dioptra GUI, navigate to the Plugins tab. Click CREATE. Enter a name and description, then click SUBMIT.

Client Method:

Use the client to create the plugin container.

PluginsCollectionClient.create(group_id: int, name: str, description: str | None = None) → dioptra.client.plugins.T[source]#

Creates a plugin.

Parameters

group_id – The id of the group that will own the plugin.
name – The name of the new plugin.
description – The description of the new plugin. Optional, defaults to None.

Example

Create a plugin called “hello” with a description.

plugin = client.plugins.create(
    group_id, "hello", "This is a Hello World Plugin"
)

Returns: The response from the Dioptra API.

Step 3: Create a Plugin File#

Next, add your Python code to the container.

Click into your newly created Plugin. Within the Plugin container, click the “Create” button in the Plugin Files window.

In the Plugin file editor, provide a filename, a description, and paste or upload your Python code (from Step 1) into the code editor.

Client Method:

Use the client.plugins.files.create() method to upload code and register tasks simultaneously.

PluginFilesSubCollectionClient.create(plugin_id: str | int, filename: str, contents: str, function_tasks: list[dict[str, Any]] | None = None, artifact_tasks: list[dict[str, Any]] | None = None, description: str | None = None) → dioptra.client.plugins.T[source]#

Creates a plugin file.

Either function_tasks or artifact_tasks should be provided. Mixing the two types of tasks is not recommended.

Parameters

plugin_id – The id for the plugin that will own the new plugin file.
filename – The filename for the new plugin file.
contents – The contents of the new Python file.
function_tasks – The information needed to register plugin function tasks contained in the plugin file, a list. Can be empty.
artifact_tasks – The information needed to register plugin artifact tasks contained in the plugin file, a list. Can be empty.
description – The description of the new plugin file. Optional, defaults to None.

Example

Attach Python code embedded in a string to a Plugin, and register a task with two input parameters and one output parameter.

file = client.plugins.files.create(
    plugin_id=plugin["id"],
    filename="hello.py",
    content=PYTHON_CONTENTS,
    tasks=[
        {
            "name": "hello_world",
            "inputParams": [
                {
                    "name": "greeting",
                    "parameterType": string_param_type_id,
                    "required": True,
                },
                {
                    "name": "name",
                    "parameterType": string_param_type_id,
                    "required": True,
                },
            ],
            "outputParams": [
                {
                    "name": "message",
                    "parameterType": string_param_type_id,
                }
            ],
        }
    ],
)

Returns: The response from the Dioptra API.

Step 4: Register Tasks (GUI only)#

Finally, register the tasks so they are visible to Dioptra.

Use the Task Form on the right side of the file editor:

For Functions: Click “Import Function Tasks” to auto-detect and register decorated functions (requires type annotations in Python code). Alternatively, register tasks manually:
- Task Name: Must match the Python Function Name exactly.
- Input Params: Add parameters matching your function arguments exactly.
- Output Params: Define names for the returned values.
For Artifacts: You must manually register the task.
- Task Name: Must match the Python Class Name exactly.
- Output Params: Select the Parameter Type that corresponds to the object produced by the deserialize method.

All inputs and outputs require a Parameter Type for validation. See Plugin Parameter Types for more.

This is done as part of the create() method in step 3.

Step 5: Save and Confirm (GUI only)#

Once the tasks appear in the list (GUI) or the API call returns successfully (Python Client), your plugin is ready for use in experiments.

Create Plugins

Contents

Create Plugins#

Prerequisites#

Plugin Creation Workflow#

Step 1: Prepare your Python Code#

Step 2: Create the Plugin Container#

Step 3: Create a Plugin File#

Step 4: Register Tasks (GUI only)#

Step 5: Save and Confirm (GUI only)#

See Also#