Add documentation about the available user capabilities and how to customize them.

felixarntz · felixarntz · commit a1d972bdca61 · 2025-01-07T12:40:23.000-08:00
diff --git a/docs/Customizing-the-Available-Capabilities.md b/docs/Customizing-the-Available-Capabilities.md
@@ -0,0 +1,104 @@
+[Back to overview](./README.md)
+
+# Customizing the Available Capabilities
+
+The AI Services comes with several custom user capabilities which are granted to users based on certain existing capabilities by default. This behavior can be modified to fine tune which users on a WordPress site are able to use the AI capabilities.
+
+## Available capabilities
+
+Here is a list of the available user capabilities, what they are for, and how they are granted by default:
+
+* `ais_manage_services`: Base capability which controls which users can access the _Settings > AI Services_ screen and configure AI service credentials.
+  * By default, all users with the `manage_options` WordPress Core capability (typically users with the administrator role) are granted this capability.
+  * Example check: `current_user_can( 'ais_manage_services' )`
+* `ais_access_services`: Base capability which controls which users can use AI features using any of the configured AI services.
+  * By default, all users with the `edit_posts` WordPress Core capability (typically users with the contributor role or higher) are granted this capability.
+  * Example check: `current_user_can( 'ais_access_services' )`
+* `ais_access_service`: Meta capability which controls which users can use AI features using a _specific_ configured AI service.
+  * By default, any user with the `ais_access_services` base capability will also be granted this meta capability.
+  * Example check: `current_user_can( 'ais_access_service', 'google' )`
+* `ais_use_playground`: Meta capability which controls which users can access and use the _Tools > AI Playground_ screen.
+  * By default, any user with the `ais_access_services` base capability will also be granted this meta capability.
+  * Example check: `current_user_can( 'ais_use_playground' )`
+
+## How to customize the default behavior
+
+The AI Services plugin's `ais_load_services_capabilities` action hook can be used to customize the way that these capabilities are granted by default. It receives an instance of a capability controller class which exposes methods to change the behavior.
+
+Below are some examples of how this action hook could be used:
+
+### Altering which WordPress Core capabilities the plugin capabilities are granted based on
+
+You can alter which WordPress Core capability a user needs to have to be granted one of the plugin's capabilities. For example, you could use the following snippet to "bump" the requirement for accessing AI services to `manage_options` which would mean that (typically) only administrators would be able to access any AI features based on these services.
+
+```php
+add_action(
+	'ais_load_services_capabilities',
+	function ( $capability_controller ) {
+		$capability_controller->grant_cap_for_base_caps(
+			'ais_access_services',
+			array( 'manage_options' )
+		);
+	}
+);
+```
+
+### Not granting any of the plugin capabilities based on existing WordPress Core capabilities
+
+You can set the required WordPress Core capabilities for all base capabilities of the AI Services plugin to an empty array, to prevent them from being granted based on other capabilities altogether. Note that if you do that you will need to implement another mechanism to grant the capabilities yourself - otherwise no user will be able to use the AI Services plugin.
+
+The following snippet would disable granting the plugin capabilities based on any WordPress Core capabilities:
+
+```php
+add_action(
+	'ais_load_services_capabilities',
+	function ( $capability_controller ) {
+		$capability_controller->grant_cap_for_base_caps( 'ais_access_services', array() );
+		$capability_controller->grant_cap_for_base_caps( 'ais_manage_services', array() );
+	}
+);
+```
+
+### Altering for a specific AI service which users can access it
+
+Instead of modifying the required WordPress Core capability to access _all_ AI services, you could also more granularly alter the conditions required to access a _specific_ AI service. This is done by providing a custom callback function to resolve the `ais_access_service` meta capability.
+
+Here is an example which would lead to the `openai` AI service to be only accessible to users with both the `ais_access_services` capability and the `manage_options` capability (typically administrators), while the other AI services would continue to be accessible to anyone with the `ais_access_services` capability.
+
+```php
+add_action(
+	'ais_load_services_capabilities',
+	function ( $capability_controller ) {
+		$capability_controller->set_meta_map_callback(
+			'ais_access_service',
+			function ( int $user_id, string $service_slug ) {
+				$required_base_caps = array( 'ais_access_services' );
+				if ( 'openai' === $service_slug ) {
+					$required_base_caps[] = 'manage_options';
+				}
+				return $required_base_caps;
+			}
+		);
+	}
+);
+```
+
+### Disabling access to the AI Playground
+
+Other than customizing which users are granted a certain capability, you can also decide to not grant a capability to any users, effectively disabling the underlying feature.
+
+For example, the following snippet would prevent any user from accessing and using the AI Playground administration screen, by using the special WordPress Core capability `do_not_allow`:
+
+```php
+add_action(
+	'ais_load_services_capabilities',
+	function ( $capability_controller ) {
+		$capability_controller->set_meta_map_callback(
+			'ais_use_playground',
+			function () {
+				return array( 'do_not_allow' );
+			}
+		);
+	}
+);
+```
diff --git a/docs/README.md b/docs/README.md
@@ -6,4 +6,5 @@
 * [Accessing AI Services with WP-CLI](./Accessing-AI-Services-with-WP-CLI.md)
 * [Implementing and Registering a New AI Service](./Implementing-and-Registering-a-New-AI-Service.md)
 * [Customizing AI Services Model Parameters](Customizing-AI-Services-Model-Parameters.md)
+* [Customizing the Available Capabilities](Customizing-the-Available-Capabilities.md)
 * [Enabling the Assistant Chatbot Feature](./Enabling-the-Assistant-Chatbot-Feature.md)
diff --git a/includes/Services/Services_Loader.php b/includes/Services/Services_Loader.php
@@ -127,9 +127,11 @@ function () {
 				 *
 				 * This hook allows you to modify the rules for how these capabilities are granted. The capabilities
 				 * available in the controller are:
+				 *
 				 * - 'ais_manage_services' (base capability)
 				 * - 'ais_access_services' (base capability)
 				 * - 'ais_access_service' (meta capability, called with the specific service slug as parameter)
+				 * - 'ais_use_playground' (meta capability)
 				 *
 				 * @since 0.1.0
 				 *
diff --git a/readme.txt b/readme.txt
@@ -241,6 +241,10 @@ add_filter(
 
 The same approach works for any other services too. Simply use the correct service slug, e.g. `openai` for the OpenAI integration and `anthropic` for the Anthropic integration.
 
+= Which user capabilities are available and how can I customize them? =
+
+[Please see the documentation article on customizing the available plugin capabilities.](https://github.com/felixarntz/ai-services/blob/main/docs/Customizing-the-Available-Capabilities.md)
+
 = Should this be in WordPress Core? =
 
 Probably not? At least not yet. While generative AI has been around for a few years, in the grand scheme of things we are still only scratching the surface of what's possible. But most importantly, the lack of standardization makes it difficult to consider built-in AI support in WordPress Core.

Original file line number	Diff line number	Diff line change
`@@ -127,9 +127,11 @@ function () {`
`127`	`127`	`*`
`128`	`128`	`* This hook allows you to modify the rules for how these capabilities are granted. The capabilities`
`129`	`129`	`* available in the controller are:`
	`130`	`+ *`
`130`	`131`	`* - 'ais_manage_services' (base capability)`
`131`	`132`	`* - 'ais_access_services' (base capability)`
`132`	`133`	`* - 'ais_access_service' (meta capability, called with the specific service slug as parameter)`
	`134`	`+ * - 'ais_use_playground' (meta capability)`
`133`	`135`	`*`
`134`	`136`	`* @since 0.1.0`
`135`	`137`	`*`