Providers

Providers are the interface between the AI subsystem and external AI. Their focus should be on converting the data requested into the format needed by the external AI, and then correctly providing the response back.

Incoming data to the Provider plugin arrives via the Manager core_ai\manager. The Manager is the connective tissue between the Provider and the Placement plugins. Likewise, all responses from the Provider plugin are handed back to the Manager before being passed to the Placement plugin.

A Provider plugin allows many "provider instances" to be defined, each of which can support a different set of configurations. This facilitates having providers for specific tasks. So, you can use a more efficient model for lightweight tasks like summarisation, and a more fully featured model for text generation. Another example is defaulting to using a cheaper model with a lower token limit, and then falling back to a more expensive model if a request is too large for the default model.

The Golden Rule:

Placements do not know about Providers, and Providers do not know about Placements. Everything should go via the Manager.

Class implementation

Providers are defined as classes in their own namespace according to their plugin name. The naming convention for a Provider class is aiprovider_<plugin name>. For example: aiprovider_openai, or aiprovider_azureai (with a corresponding namespace).

Each Provider must inherit from the \core_ai\provider abstract class.

Required Methods

They must also implement the following methods:

get_action_list(): array

This is the list of Actions that are supported by this Provider, for example the aiprovider_openai plugin defines this as:

public static function get_action_list(): array {
    return [
        \core_ai\aiactions\generate_text::class,
        \core_ai\aiactions\generate_image::class,
        \core_ai\aiactions\summarise_text::class,
    ];
}

is_provider_configured(): bool

Each provider will need to specify what it takes to be considered as configured. It is likely that each provider will have a set of keys necessary to access the external AI API.

The is_provider_configured() must return true for UI component visibility and functionality. If not overridden, it will return false by default.

For example, the aiprovider_azureai provider checks values are set for $this->apikey and $this->apiendpoint and returns the result.

public function is_provider_configured(): bool {
    return !empty($this->config['apikey']) && !empty($this->config['endpoint']);
}

Process classes

For each action supported by the provider, the provider plugin must implement a process_<action> class, where <action> is the name of the action. For example: process_generate_image.

Every process action class must inherit from the \core_ai\process_base abstract class.

The process action class must implement a process() method. This method is responsible for converting the data requested by an Action into the format needed by the external AI services API, and then correctly providing the response back from the AI in an Action Response object.

The process action classes and process method are expected by the manager to exist and be callable.

As most provider plugins will support more than one action, it is recommended to create an abstract_processor class that inherits from the \core_ai\process_base class and then have each process action class inherit from this abstract class.

For example, the aiprovider_openai plugin defines an abstract_processor class that inherits from the \core_ai\process_base class and then the process_generate_image, process_generate_text and process_summarise_text classes inherit from this abstract class.

This can be visualised as follows:

Apart from this, Providers are free to define their own structure. It should be kept in mind that Providers are designed to be a 'thin wrapper' around the external AI systems API. They shouldn't store data, or have their own UI elements (beyond what is required for configuration).

Plugin structure

Provider plugins reside in the ai/provider directory.

Each Provider is in a separate subdirectory and consists of a number of mandatory files and any other files the developer is going to use.

The typical directory layout for the Provider plugin, using OpenAI Provider as an example:

.
├── amd
│   ├── build
│   │   ├── modelchooser.min.js
│   │   └── modelchooser.min.js.map
│   └── src
│       └── modelchooser.js
├── classes
│   ├── abstract_processor.php
│   ├── aimodel
│   │   ├── gpt4o.php
│   │   └── o1.php
│   ├── form
│   │   ├── action_form.php
│   │   ├── action_generate_image_form.php
│   │   └── action_generate_text_form.php
│   ├── helper.php
│   ├── hook_listener.php
│   ├── privacy
│   │   └── provider.php
│   ├── process_generate_image.php
│   ├── process_generate_text.php
│   ├── process_summarise_text.php
│   └── provider.php
├── db
│   └── hooks.php
├── lang
│   └── en
│       └── aiprovider_openai.php
├── tests
│   ├── fixtures
│   │   ├── image_request_success.json
│   │   ├── test.jpg
│   │   └── text_request_success.json
│   ├── process_generate_image_test.php
│   ├── process_generate_text_test.php
│   ├── process_summarise_text_test.php
│   └── provider_test.php
└── version.php

Provider Settings

Settings for the Provider are defined as a Hook. Each Provider plugin should create a new classes/hook_listener.php file. This file should contain a class with a static method that defines the hook callback. create a new admin settings page using core_ai\admin\admin_settingspage_provider class. This class should implement a set_form_definition_for_aiprovider_<plugin name> method.

This method should define the settings form for the provider plugin, using the provided mform object.

For example, the aiprovider_openai plugin defines this:

namespace aiprovider_openai;
use core_ai\hook\after_ai_provider_form_hook;

class hook_listener {

    /**
     * Hook listener for the Open AI instance setup form.
     *
     * @param after_ai_provider_form_hook $hook The hook to add to the AI instance setup.
     */
    public static function set_form_definition_for_aiprovider_openai(after_ai_provider_form_hook $hook): void {
        if ($hook->plugin !== 'aiprovider_openai') {
            return;
        }

        $mform = $hook->mform;

        // Required setting to store OpenAI API key.
        $mform->addElement(
            'passwordunmask',
            'apikey',
            get_string('apikey', 'aiprovider_openai'),
            ['size' => 75],
        );
        $mform->addHelpButton('apikey', 'apikey', 'aiprovider_openai');
        $mform->addRule('apikey', get_string('required'), 'required', null, 'client');

        // Setting to store OpenAI organization ID.
        $mform->addElement(
            'text',
            'orgid',
            get_string('orgid', 'aiprovider_openai'),
            ['size' => 25],
        );
        $mform->setType('orgid', PARAM_TEXT);
        $mform->addHelpButton('orgid', 'orgid', 'aiprovider_openai');

    }

}

Because a hook is used to define the settings, Provider plugins also need to have a db/hooks.php file to register its hook callback. The specified plugin callback method is called whenever the provider instance is chosen in the provider administration settings.

For example, the aiprovider_openai plugin defines this:

defined('MOODLE_INTERNAL') || die();

$callbacks = [
    [
        'hook' => \core_ai\hook\after_ai_provider_form_hook::class,
        'callback' => \aiprovider_openai\hook_listener::class . '::set_form_definition_for_aiprovider_openai',
    ],
];

Action Settings

Each of the actions that a provider plugin supports can have its own settings. If an action requires additional settings, the provider class for the plugin should override the get_action_settings() method. The method must return an instance of core_ai\form\action_settings_form.

For example, the aiprovider_openai plugin defines this:

#[\Override]
public static function get_action_settings(
    string $action,
    array $customdata = [],
): action_settings_form|bool {
    $actionname = substr($action, (strrpos($action, '\\') + 1));
    $customdata['actionname'] = $actionname;
    $customdata['action'] = $action;
    if ($actionname === 'generate_text' || $actionname === 'summarise_text') {
        return new form\action_generate_text_form(customdata: $customdata);
    } else if ($actionname === 'generate_image') {
        return new form\action_generate_image_form(customdata: $customdata);
    }

    return false;
}

The actual settings form for the actions should be defined in the classes/form directory. For example, the aiprovider_openai plugin defines action_generate_text_form and action_generate_image_form classes. These classes should extend the core_ai\form\action_settings_form class, and must implement the definition() method.

For example, the aiprovider_openai plugin defines this:

class action_generate_text_form extends action_settings_form {
    #[\Override]
    protected function definition() {
        $mform = $this->_form;
        $actionconfig = $this->_customdata['actionconfig']['settings'] ?? [];
        $returnurl = $this->_customdata['returnurl'] ?? null;
        $actionname = $this->_customdata['actionname'];
        $action = $this->_customdata['action'];
        $providerid = $this->_customdata['providerid'] ?? 0;

        // Action model to use.
        $mform->addElement(
            'text',
            'model',
            get_string("action:{$actionname}:model", 'aiprovider_openai'),
            'maxlength="255" size="20"',
        );
        $mform->setType('model', PARAM_TEXT);
        $mform->addRule('model', null, 'required', null, 'client');
        $mform->setDefault('model', $actionconfig['model'] ?? 'gpt-4o');
        $mform->addHelpButton('model', "action:{$actionname}:model", 'aiprovider_openai');

...

Rate limiting

Provider plugins by default implement rate limiting to prevent abuse of the external AI services. This is inherited from the core_ai\provider class. Developers don't need to implement rate limiting themselves.

This default rate limiting behaviour can be changed by overriding the is_request_allowed() method core_ai\provider class.