AI: Introduce wp_supports_ai() function to control LLM-related features.

This includes a `WP_AI_SUPPORT` constant and a `wp_supports_ai` filter.

When false,
- `_wp_connectors_get_provider_settings()` will return an empty array (short-circuiting the other functionality).
- `WP_AI_Client_Prompt_Builder()` will short-circuit the construction with a `WP_Error()`. `wp_ai_client_prompt()` will still return an instance, to allow for fluidity to remain intact.

Priority: `WP_AI_SUPPORT` > `add_filter( 'wp_supports_ai', ...) > (default: true)` 

Follow-up to [61943], [61749], [61943].

Props justlevine, westonruter, gziolo, flixos90, romainmrhenry, ahortin, chrismcelroyseo, SergeyBiryukov.
See #64706.

git-svn-id: https://develop.svn.wordpress.org/trunk@62067 602fd350-edb4-49c9-b593-d223f7449a82

Author: SergeyBiryukov

src/wp-includes/ai-client.php

@@ -9,6 +9,30 @@
 
 use WordPress\AiClient\AiClient;
 
+/**
+ * Returns whether AI features are supported in the current environment.
+ *
+ * @since 7.0.0
+ *
+ * @return bool Whether AI features are supported.
+ */
+function wp_supports_ai(): bool {
+	$is_enabled = defined( 'WP_AI_SUPPORT' ) ? WP_AI_SUPPORT : true;
+
+	/**
+	 * Filters whether the current request should use AI.
+	 *
+	 * This allows plugins and 3rd-party code to disable AI features on a per-request basis, or to even override explicit
+	 * preferences defined by the site owner.
+	 *
+	 * @since 7.0.0
+	 *
+	 * @param bool $is_enabled Whether the current request should use AI. Default to WP_AI_SUPPORT constant, or true if
+	 *                         the constant is not defined.
+	 */
+	return (bool) apply_filters( 'wp_supports_ai', $is_enabled );
+}
+
 /**
  * Creates a new AI prompt builder using the default provider registry.
  *

src/wp-includes/ai-client/class-wp-ai-client-prompt-builder.php

@@ -46,6 +46,8 @@
  *
  * @since 7.0.0
  *
+ * @phpstan-import-type Prompt from PromptBuilder
+ *
  * @method self with_text(string $text) Adds text to the current message.
  * @method self with_file($file, ?string $mimeType = null) Adds a file to the current message.
  * @method self with_function_response(FunctionResponse $functionResponse) Adds a function response to the current message.
@@ -170,14 +172,14 @@ class WP_AI_Client_Prompt_Builder {
 	 *
 	 * @since 7.0.0
 	 *
-	 * @param ProviderRegistry                                                                 $registry The provider registry for finding suitable models.
-	 * @param string|MessagePart|Message|array|list<string|MessagePart|array>|list<Message>|null $prompt   Optional. Initial prompt content.
-	 *                                                                                                    A string for simple text prompts,
-	 *                                                                                                    a MessagePart or Message object for
-	 *                                                                                                    structured content, an array for a
-	 *                                                                                                    message array shape, or a list of
-	 *                                                                                                    parts or messages for multi-turn
-	 *                                                                                                    conversations. Default null.
+	 * @param ProviderRegistry $registry The provider registry for finding suitable models.
+	 * @param Prompt           $prompt   Optional. Initial prompt content.
+	 *                                   A string for simple text prompts,
+	 *                                   a MessagePart or Message object for
+	 *                                   structured content, an array for a
+	 *                                   message array shape, or a list of
+	 *                                   parts or messages for multi-turn
+	 *                                   conversations. Default null.
 	 */
 	public function __construct( ProviderRegistry $registry, $prompt = null ) {
 		try {
@@ -289,26 +291,35 @@ public function __call( string $name, array $arguments ) {
 
 		// Check if the prompt should be prevented for is_supported* and generate_*/convert_text_to_speech* methods.
 		if ( self::is_support_check_method( $name ) || self::is_generating_method( $name ) ) {
-			/**
-			 * Filters whether to prevent the prompt from being executed.
-			 *
-			 * @since 7.0.0
-			 *
-			 * @param bool                        $prevent Whether to prevent the prompt. Default false.
-			 * @param WP_AI_Client_Prompt_Builder $builder A clone of the prompt builder instance (read-only).
-			 */
-			$prevent = (bool) apply_filters( 'wp_ai_client_prevent_prompt', false, clone $this );
+			// If AI is not supported, then there's no need to apply the filter as the prompt will be prevented anyway.
+			$is_ai_disabled = ! wp_supports_ai();
+			$prevent        = $is_ai_disabled;
+			if ( ! $prevent ) {
+				/**
+				 * Filters whether to prevent the prompt from being executed.
+				 *
+				 * @since 7.0.0
+				 *
+				 * @param bool                        $prevent Whether to prevent the prompt. Default false.
+				 * @param WP_AI_Client_Prompt_Builder $builder A clone of the prompt builder instance (read-only).
+				 */
+				$prevent = (bool) apply_filters( 'wp_ai_client_prevent_prompt', false, clone $this );
+			}
 
 			if ( $prevent ) {
 				// For is_supported* methods, return false.
 				if ( self::is_support_check_method( $name ) ) {
 					return false;
 				}
 
+				$error_message = $is_ai_disabled
+					? __( 'AI features are not supported in this environment.' )
+					: __( 'Prompt execution was prevented by a filter.' );
+
 				// For generate_* and convert_text_to_speech* methods, create a WP_Error.
 				$this->error = new WP_Error(
 					'prompt_prevented',
-					__( 'Prompt execution was prevented by a filter.' ),
+					$error_message,
 					array(
 						'status' => 503,
 					)
@@ -423,7 +434,8 @@ private static function is_generating_method( string $name ): bool {
 	protected function get_builder_callable( string $name ): callable {
 		$camel_case_name = $this->snake_to_camel_case( $name );
 
-		if ( ! is_callable( array( $this->builder, $camel_case_name ) ) ) {
+		$method = array( $this->builder, $camel_case_name );
+		if ( ! is_callable( $method ) ) {
 			throw new BadMethodCallException(
 				sprintf(
 					/* translators: 1: Method name. 2: Class name. */
@@ -434,7 +446,7 @@ protected function get_builder_callable( string $name ): callable {
 			);
 		}
 
-		return array( $this->builder, $camel_case_name );
+		return $method;
 	}
 
 	/**

src/wp-includes/class-wp-connector-registry.php

@@ -170,6 +170,11 @@ public function register( string $id, array $args ): ?array {
 			return null;
 		}
 
+		if ( 'ai_provider' === $args['type'] && ! wp_supports_ai() ) {
+			// No need for a `doing_it_wrong` as AI support is disabled intentionally.
+			return null;
+		}
+
 		$connector = array(
 			'name'           => $args['name'],
 			'description'    => isset( $args['description'] ) && is_string( $args['description'] ) ? $args['description'] : '',