[docs] AI: Update AI documentation (MDL-83402) [5.0]

docs/apis/plugintypes/ai/index.md

@@ -7,33 +7,56 @@ tags:
   - Placement
 ---
 
-The AI subsystem in the LMS is designed to be extensible, allowing for the integration of external AI services.
-This is achieved through the use of AI plugins, which are divided into two types: Providers and Placements.
+The [AI subsystem](/apis/subsystems/ai/index.md) provides a way for developers to integrate external AI services into Moodle LMS.
 
-### Placements
+The design of the AI subsystem features two distinct plugin types:
 
-The aim of Placements is to provide a consistent UX and UI for users when they use AI backed functionality.
+- [Provider plugins](/apis/plugintypes/ai/provider.md)
+- [Placement plugins](/apis/plugintypes/ai/placement.md)
 
-Placement plugins leverage the functionality of the other components of the AI subsystem.
-This means plugin authors can focus on how users interact with the AI functionality, without needing to
-implement the AI functionality itself.
+This design allows for independent development of each plugin. The Provider plugin is not aware of the
+Placement plugin, and the Placement plugin is not aware of the Provider plugin. All communication between the two plugins
+travels through the Manager.
 
-Because Placements are LMS plugins in their own right and are not "other" types of LMS plugins,
-it gives great flexibility in how AI functionality is presented to users.
+```mermaid
+sequenceDiagram
+    User->>Placement: Input action
+    Placement->>Manager: Action data
+    Manager->>Provider: Formatted action data
+    Provider->>External AI: Send data
+    External AI-->>Provider: Receive response
+    Provider-->>Manager: Response data
+    Manager-->>Placement: Formatted response data
+    Placement-->>User: Action completed
+```
 
-See the [Placements](/apis/plugintypes/ai/placement.md) documentation for more information
-on developing Placement plugins.
+### Provider plugins
 
-### Providers
+Providers are the interface between the [AI subsystem](/apis/subsystems/ai/index.md) and external AI.
+Their focus is on formatting actions, passing them to the external AI system, and providing the response.
 
-Provider plugins are the interface between the LMS AI subsystem and external AI systems.
-Their focus is on 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.
+Currently, Moodle supports the following AI Providers in core:
 
-Because of this design the Providers that provide the AI Actions can be swapped out, mix and matched
-or upgraded; both without the need to update the Placement code and without the need to change the
-way users interact with the functionality.
+- OpenAI `aiprovider_openai`
+- Azure AI `aiprovider_azureai`
 
 See the [Providers](/apis/plugintypes/ai/provider.md) documentation for more information
 on developing Provider plugins.
+
+### Placement plugins
+
+Placements provide a consistent UX and UI for users when they use AI backed functionality (e.g. generating an image).
+
+Placement plugins leverage the functionality of the other components of the [AI subsystem](/apis/subsystems/ai/index.md).
+This means plugin authors can focus on how users interact with the AI functionality, without needing to
+implement the AI functionality itself.
+
+Because Placements are plugins in their own right, it allows for greater flexibility in how AI functionality is presented to users.
+
+Currently, Moodle supports the following AI Placements:
+
+- Course Assistance `aiplacement_courseassist`
+- HTML Text Editor `aiplacement_editor`
+
+See the [Placements](/apis/plugintypes/ai/placement.md) documentation for more information
+on developing Placement plugins.

docs/apis/plugintypes/ai/placement.md

@@ -6,30 +6,37 @@ tags:
   - Placement
 ---
 
-The aim of Placements is to provide a consistent UX and UI for users when they use AI backed functionality.
+Placements provide a consistent UX and UI for users when they use AI backed functionality (e.g. generating an image).
 
-Placement plugins leverage the functionality of the other components of the AI subsystem.
+Placement plugins leverage the functionality of the other components of the [AI subsystem](/apis/subsystems/ai/index.md).
 This means plugin authors can focus on how users interact with the AI functionality, without needing to
 implement the AI functionality itself.
 
-Because Placements are LMS plugins in their own right and are not "other" types of LMS plugins,
-it gives great flexibility in how AI functionality is presented to users.
+Because Placements are plugins in their own right, it allows for greater flexibility in how AI functionality is presented to users.
+
+Outgoing data from the Placement plugin travels via the Manager `core_ai\manager`.
+The Manager is the connective tissue between the [Provider](/apis/plugintypes/ai/provider.md) and the Placement plugins.
+Likewise, all responses from the Provider plugin are handed back to the Manager before being passed to the Placement plugin.
 
 :::warning The Golden Rule:
 
-Placements DO NOT know about Providers, and Providers DO NOT know about Placements.
+Placements **do not** know about Providers, and Providers **do not** know about Placements.
 Everything should go via the Manager.
 
 :::
 
+## Class implementation
+
 Placements are defined as classes in their own namespace according to their plugin name.
-The naming convention for Action classes is `aiplacement_<plugin name>`,
-for example: `aiplacement_editor`. With corresponding namespaces.
+The naming convention for a Placement class is `aiplacement_<plugin name>`.
+For example: `aiplacement_editor` (with a corresponding namespace).
 
-Each Placement MUST inherit from the `\core_ai\placement` abstract class.
+Each Placement **must** inherit from the `\core_ai\placement` abstract class.
 They must also implement the following methods:
 
-- `get_action_list(): array` This is the list of Actions that are supported by this Placement, for example the `aiplacement_editor` plugin defines this as:
+**`get_action_list(): array`**
+
+This is the list of Actions that are supported by this Placement, for example the `aiplacement_editor` plugin defines this as:
 
 ```php
 public function get_action_list(): array {
@@ -40,17 +47,43 @@ public function get_action_list(): array {
 }
 ```
 
-## Capabilities and Permissions
+## Capabilities and permissions
+
+Placements provide a way for a user to carry out an Action.
+Placements are responsible for determining who can use a particular Action, and where it can be used.
+It is not the job of Providers to determine access.
 
-Placements are responsible for determining who and where a Placement (and by extension an Action can be used).
-It is not the job of Actions or Providers to determine access.
+```php
+$capabilities = [
+    'aiplacement/editor:generate_image' => [
+        'captype' => 'write',
+        'contextlevel' => CONTEXT_COURSE,
+        'archetypes' => [
+            'manager' => CAP_ALLOW,
+            'editingteacher' => CAP_ALLOW,
+            'teacher' => CAP_ALLOW,
+            'student' => CAP_ALLOW,
+        ],
+    ],
+...
+```
 
-## Action Processing
+## Action processing
 
 The following is the basic workflow in order for a placement to have an action processed for a user request:
 
-- The Placement instantiates a new action object of type they wish to use.
-- The action must be instantiated and passing it the required data. Each action will define what configuration it needs. As an example:
+```mermaid
+sequenceDiagram
+    Placement->>Manager: New action
+    Manager->>Provider: Process action
+    Provider->>Manager: Get response
+    Manager->>Placement: Pass response
+```
+
+### Step 1
+
+- The Placement instantiates a new Action object of type they wish to use.
+- The Action must be instantiated with the required data. Each action will define what configuration it needs. As an example:
 
 ```php
 // Prepare the action.
@@ -65,65 +98,73 @@ $action = new \core_ai\aiactions\generate_image(
 );
 ```
 
-- The Placement then instantiates the Manager class and calls `process_action()`
-- passing in the configured action object:
+### Step 2
+
+- The Placement then instantiates the Manager class `core_ai\manager`.
+- The Manager calls `process_action()`, passing in the configured Action object. As an example:
 
 ```php
 // Send the action to the AI manager.
 $manager = \core\di::get(\core_ai\manager::class);
 $response = $manager->process_action($action);
 ```
 
-- The process_action() method will then return a response object (instance of `responses\response_base`).
-- It is up to the Placement to check for success (or not) of the response and pass the result back to the
-  user or for further processing.
+### Step 3
+
+- The `process_action()` method then returns a response object (instance of `responses\response_base`).
+- It is up to the Placement to check for success/failure of the response and pass the result back to the
+  user.
 
-## Plugin Structure
+## Plugin structure
 
-Placement plugins reside in the `ai/placement` directory.
+The Placement plugins reside in the `ai/placement` directory.
 
-Each Placement is in a separate subdirectory and consists of a number of mandatory files and any other
-files the developer is going to use.
+Each Placement is in a separate subdirectory and consists of a number of mandatory and supportive files that will
+be necessary for development.
 
-The following is the typical structure of a Placement plugin, using the Editor Placement as an example:
+<details>
+  <summary>The typical directory layout for the Placement plugin, using the Editor Placement as an example:</summary>
 
-```bash
+```console
 .
 ├── classes
 │   ├── external
 │   │   ├── generate_image.php
 │   │   └── generate_text.php
 │   ├── placement.php
-│   └── privacy
-│       └── provider.php
+│   ├── privacy
+│   │   └── provider.php
+│   └── utils.php
 ├── db
 │   ├── access.php
 │   └── services.php
 ├── lang
 │   └── en
 │       └── aiplacement_editor.php
+├── tests
+│   └── utils_test.php
 └── version.php
-
 ```
 
+</details>
+
 ## Settings
 
 Settings for the Placement should be defined in the `settings.php` file.
 Each Placement plugin should create a new admin settings page using `core_ai\admin\admin_settingspage_provider` class.
 
-This is the same as for Provider plugins, for example:
+This is the same for Provider plugins, for example:
 
 ```php
 use core_ai\admin\admin_settingspage_provider;
 
 if ($hassiteconfig) {
     // Placement specific settings heading.
     $settings = new admin_settingspage_provider(
-        'aiprovider_openai',
-        new lang_string('pluginname', 'aiprovider_openai'),
+        'aiplacement_courseassist',
+        new lang_string('pluginname', 'aiplacement_courseassist'),
         'moodle/site:config',
         true,
     );
-
 ...
 ```