AI: Update PHP AI Client to 1.5.0 and introduce WP_AI_Client_Embedding_Builder

[JasonTheAdams]

Trac: https://core.trac.wordpress.org/ticket/65638

What

Updates the bundled PHP AI Client library to 1.4.0 and introduces embedding generation support in core.

Library update

Regenerated src/wp-includes/php-ai-client/ via bash tools/php-ai-client/installer.sh --version=1.4.0. The headline feature of 1.4.0 is embedding generation: a new EmbeddingBuilder, embedding lifecycle events, Embedding/EmbeddingResult DTOs, and a shared ModelResolver. See the 1.4.0 and 1.5.0 release notes for a full list of changes.

New: WP_AI_Client_Embedding_Builder

A WordPress wrapper around the SDK's new EmbeddingBuilder, following the exact pattern established by WP_AI_Client_Prompt_Builder:

• snake_case method naming proxied to the SDK's camelCase methods via __call().
• WP_Error handling instead of exceptions: non-generating methods never throw; once an error occurs the instance enters an error state that preserves the fluent interface, and the WP_Error is returned from the generating methods (generate_embedding_result(), generate_embedding(), generate_embeddings()).
• Respects wp_supports_ai() and the existing wp_ai_client_default_request_timeout filter.
• Adds a wp_ai_client_prevent_embedding filter, analogous to wp_ai_client_prevent_prompt.
• Error codes use an embedding_* prefix (e.g. embedding_network_error, embedding_invalid_argument) with HTTP status codes for REST-friendly errors.

Also introduces the variadic wp_ai_client_embedding() entry point, analogous to wp_ai_client_prompt():

$embeddings = wp_ai_client_embedding( 'first input', 'second input' )->generate_embeddings();

Testing

• php -l and PHPCS pass on all changed files.
• Autoloader smoke test: WordPress\AiClient\AiClient resolves after the update.
• Verified via reflection that all 11 proxied snake_case methods map to existing EmbeddingBuilder methods.

🤖 Generated with Claude Code

Shared base class: WP_AI_Client_Builder

Since the prompt and embedding builders share nearly all of their machinery, it now lives in an abstract WP_AI_Client_Builder base class: the snake_case __call() proxying, WP_Error error-state handling, exception-to-WP_Error conversion, and default request timeout setup. Child classes supply the SDK builder, error code prefix, prevent filter, and method maps via abstract methods. No behavior changes for WP_AI_Client_Prompt_Builder — error codes, filter names, and _doing_it_wrong() notices (which report the concrete class name) are identical to 7.0.

Test updates

PHP AI Client 1.4.0 moved model selection state (model, registry, providerIdOrClassName, requestOptions) from the SDK PromptBuilder onto its new ModelResolver; the test reflection helper now follows properties there.

Dedicated tests were added for WP_AI_Client_Embedding_Builder and wp_ai_client_embedding(), covering the wrapper behavior (not the SDK): constructor input parsing, timeout filter handling, fluent proxying and error-state semantics, the wp_supports_ai() / wp_ai_client_prevent_embedding gates, exception-to-WP_Error mapping, and generation via a mock embedding model. The full ai-client group passes: 298 tests, 747 assertions.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @claude, @chubes4, @dugyen.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

Core Committers: Use this line as a base for the props when committing in SVN:

Props jason_the_adams, gziolo, dkotter, jorgefilipecosta, jeffpaul.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[dkotter]

Haven't tested this out yet but overall this looks good to me, noting most of what's here is coming from the PHP AI Client repo so I haven't reviewed any of that closely. Left a few comments that may be worth discussing

[chubes4]

Created the corresponding Core Trac ticket: https://core.trac.wordpress.org/ticket/65638

@JasonTheAdams please add the full ticket URL to this PR description to clear the missing-ticket check. The ticket links this implementation, PHP AI Client #244, and the 1.4.0 release.

[JasonTheAdams]

Done! Thanks, @chubes4!

[dkotter]

Code looks good here to me and I've tested these changes out using the OpenAI Provider (from this PR) and the test WP-CLI command we have in the AI plugin (from this PR, with a few changes to utilize the new wp_ai_client_embedding function). Everything works as I'd expect.

Just as a personal opinion/thought, I think it would be nice to be able to pass in an array of data to get multiple embeddings.

Right now you have to do:

wp_ai_client_embedding( 'first input', 'second input' )->generate_embeddings()

As this won't work:

wp_ai_client_embedding( array( 'first input', 'second input' ) )->generate_embeddings()

The second feels a bit more natural to me but not something I feel strongly about. Can still use an array as the argument and just spread the result:

wp_ai_client_embedding( ...array( 'first input', 'second input' ) )->generate_embeddings()

[JasonTheAdams]

Thanks, @dkotter! My personal preference is to have folks spread the array for variadic parameters, as you showed in your third example. The reason being that it keeps the function signature simple and less prone to bugs. I'm a fan of variadic parameters because PHP doesn't support array generics, so it's a great way to have an array parameter that's strictly typed.

[gziolo]

It's now possible to land changes planned for WordPress 7.2. I would be in favor of landing this patch early to allow in-depth testing with plugins that implement the proposed AI interfaces. The first step would be to ensure all code references to WordPress versions are updated to 7.2.0 instead of 7.1.0.

[dugyen]

Test Report

Ticket: Trac #65638

Result: PASS, with one carried-forward bug flagged ⚠️

Environment

• WordPress: 7.1 (dev)
• PHP: 8.5.7
• Test method: WP-CLI wp eval-file against the live install (no PHPUnit test-suite checkout on this install, so the 2 new test files + 1 modified test file were skipped by patch; all 20 src/ files applied cleanly)
• Database: SQLite

What the PR does

Bumps the bundled PHP AI Client SDK from 1.3.1 to 1.4.0 (adds embedding support), extracts the shared logic of WP_AI_Client_Prompt_Builder into a new abstract WP_AI_Client_Builder base class, and adds a new WP_AI_Client_Embedding_Builder (+ wp_ai_client_embedding() entry point and wp_ai_client_prevent_embedding filter) on top of that base class.

Steps taken

1. Backed up the 9 modified src/ files; confirmed none of the 11 new src/ files already existed (no conflicts).
2. Applied the full patch (patch -p2); all 20 src/ files applied cleanly.
3. php -l on all 20 changed/added files — clean.
4. Verified autoloading resolves every new class (WordPress\AiClient\Builders\EmbeddingBuilder, WordPress\AiClient\Results\DTO\Embedding/EmbeddingResult, the new WP_AI_Client_Builder/WP_AI_Client_Embedding_Builder, etc.) and that AiClient::VERSION reads 1.4.0.
5. Exercised wp_ai_client_embedding() end-to-end: entry point, fluent chaining, is_supported(), generate_embedding() with no provider configured, and the new wp_ai_client_prevent_embedding filter.
6. Regression-checked wp_ai_client_prompt() still works correctly after being refactored onto the new base class (chaining, is_supported(), generate_text()).
7. Verified the new $builder_type parameter on the wp_ai_client_default_request_timeout filter fires with the correct class name for both builders.
8. Specifically tested whether the TypeError-fatal bug from AI: Catch Throwable in WP_AI_Client_Prompt_Builder so TypeErrors become WP_Error #12256 (trac #65505, which I tested and confirmed separately) was carried into the new shared base class — it was.
9. Restored all 9 modified files from backup (SHA-1 verified) and deleted all 11 new files, plus 2 now-empty directories the patch created.

Actual result

• Library bump, refactor, and new embedding builder all work as described. AiClient::VERSION is 1.4.0; every new class autoloads; wp_ai_client_embedding() returns a working WP_AI_Client_Embedding_Builder; fluent chaining, the embedding_invalid_argument/embedding_prevented WP_Error paths, and the new wp_ai_client_prevent_embedding filter all behaved exactly as expected. wp_ai_client_prompt() shows no regression after being moved onto the shared base class.
• However: this PR carries forward the exact TypeError-escapes-uncaught bug already reported and fixed in AI: Catch Throwable in WP_AI_Client_Prompt_Builder so TypeErrors become WP_Error #12256 / trac #65505 — and, because that fix hasn't landed on trunk yet, this PR's refactor reproduces the same catch ( Exception $e ) (not Throwable) in the new shared WP_AI_Client_Builder::__call(). Confirmed live:

  wp_ai_client_embedding('x')->using_dimensions( array( 256 ) );

  (an array can never coerce to the SDK's int $dimensions parameter) throws an uncaught TypeError straight out of __call(), instead of being caught and returned as a graceful WP_Error — exactly the same failure mode as the using_temperature()/TypeError case in AI: Catch Throwable in WP_AI_Client_Prompt_Builder so TypeErrors become WP_Error #12256, just now on a different (strict int) setter.
• Because WP_AI_Client_Builder::__call() is now shared by inheritance, this single catch ( Exception $e ) gap affects both WP_AI_Client_Prompt_Builder and the brand-new WP_AI_Client_Embedding_Builder — i.e. this PR doubles the surface area of the still-open AI: Catch Throwable in WP_AI_Client_Prompt_Builder so TypeErrors become WP_Error #12256 bug rather than fixing or avoiding it.
• Recommend rebasing this PR on top of AI: Catch Throwable in WP_AI_Client_Prompt_Builder so TypeErrors become WP_Error #12256's fix (or applying the identical Throwable widening to WP_AI_Client_Builder::__call() and its constructor's catch block) before/at merge, so the new embedding builder doesn't ship with the same known fatal-on-bad-input issue on day one.

Additional notes

• wp_supports_ai() returned true on this install even with no AI provider configured, so generate_embedding()/generate_text() proceed past the "AI disabled" gate and fail gracefully downstream with *_invalid_argument ("No models found that support embedding_generation.") rather than short-circuiting earlier — expected SDK behavior, not a bug.
• Did not exercise real embedding generation end-to-end (needs a configured AI provider/API key); confirmed the pieces reachable without one: entry point, chaining, error-state propagation, filter wiring, autoloading, and the base-class exception-handling gap above.
• All 9 modified files restored from backup with SHA-1 verified; all 11 new files (and the empty directories they left behind) removed; site back to AiClient::VERSION 1.3.1 / pre-patch state.

Support content

1. Reproduce the carried-forward TypeError bug (patched code):

$builder = wp_ai_client_embedding( 'hello world' );
$builder->using_dimensions( array( 256 ) );  // fatals: uncaught TypeError

Output:

Fatal error: Uncaught TypeError:
WordPress\AiClient\Builders\EmbeddingBuilder::usingDimensions():
Argument #1 ($dimensions) must be of type int, array given, called in
.../wp-includes/ai-client/class-wp-ai-client-builder.php on line 238

2. Happy-path / regression checks (patched code):

$b = wp_ai_client_embedding( 'hello world' );
$b->using_dimensions( 256 );                 // fluent, same instance
$b->is_supported();                          // false, no fatal
$b->generate_embedding();                    // WP_Error: embedding_invalid_argument

add_filter( 'wp_ai_client_prevent_embedding', '__return_true' );
wp_ai_client_embedding( 'hi' )->generate_embedding();
// WP_Error: embedding_prevented, status 503

$p = wp_ai_client_prompt( 'Test prompt' );
$p->using_temperature( 0.7 );                 // fluent, same instance
$p->generate_text();                          // WP_Error: prompt_invalid_argument
// -> no regression from the WP_AI_Client_Builder refactor

---

🤖 Test performed with Claude Code

[dugyen]

Recommended fix for the carried-forward TypeError bug

Following up on the test report above — here's a concrete, tested fix for the issue: WP_AI_Client_Builder still only catches Exception, not Throwable, so a TypeError from a strict-typed SDK setter (e.g. usingDimensions(int), usingTemperature(float)) escapes uncaught instead of becoming a graceful WP_Error.

Applying the exact same pattern PR #12256 used (widen both catch clauses to Throwable, rename exception_to_wp_error() → throwable_to_wp_error()) to src/wp-includes/ai-client/class-wp-ai-client-builder.php fixes it for both builders at once, since they now share this code:

--- a/src/wp-includes/ai-client/class-wp-ai-client-builder.php
+++ b/src/wp-includes/ai-client/class-wp-ai-client-builder.php
@@ -65,9 +65,9 @@
 	public function __construct( ProviderRegistry $registry, $input = null ) {
 		try {
 			$this->builder = $this->create_sdk_builder( $registry, $input );
-		} catch ( Exception $e ) {
+		} catch ( Throwable $e ) {
 			$this->builder = $this->create_sdk_builder( $registry, null );
-			$this->error   = $this->exception_to_wp_error( $e );
+			$this->error   = $this->throwable_to_wp_error( $e );
 		}
 
 		$default_timeout = 30.0;
@@ -243,8 +243,8 @@
 			}
 
 			return $result;
-		} catch ( Exception $e ) {
-			$this->error = $this->exception_to_wp_error( $e );
+		} catch ( Throwable $e ) {
+			$this->error = $this->throwable_to_wp_error( $e );
 
 			if ( $this->is_generating_method( $name ) ) {
 				return $this->error;
@@ -254,36 +254,36 @@
 	}
 
 	/**
-	 * Converts an exception into a WP_Error with a structured error code and message.
+	 * Converts a throwable into a WP_Error with a structured error code and message.
 	 *
-	 * This method maps different exception types to specific WP_Error codes and HTTP status codes.
+	 * This method maps different throwable types to specific WP_Error codes and HTTP status codes.
 	 * The presence of the status codes means these WP_Error objects can be easily used in REST API responses
 	 * or other contexts where HTTP semantics are relevant.
 	 *
 	 * @since 7.0.0
 	 * @since 7.1.0 Moved from `WP_AI_Client_Prompt_Builder` to the `WP_AI_Client_Builder` base class.
 	 *
-	 * @param Exception $e The exception to convert.
+	 * @param Throwable $throwable The throwable to convert.
 	 * @return WP_Error The resulting WP_Error object.
 	 */
-	protected function exception_to_wp_error( Exception $e ): WP_Error {
+	protected function throwable_to_wp_error( Throwable $throwable ): WP_Error {
 		$prefix = $this->get_error_code_prefix();
 
-		if ( $e instanceof NetworkException ) {
+		if ( $throwable instanceof NetworkException ) {
 			$error_code  = $prefix . '_network_error';
 			$status_code = 503;
-		} elseif ( $e instanceof ClientException ) {
+		} elseif ( $throwable instanceof ClientException ) {
 			// `ClientException` uses HTTP status codes as exception codes, so we can rely on them.
 			$error_code  = $prefix . '_client_error';
-			$status_code = $e->getCode() ? $e->getCode() : 400;
-		} elseif ( $e instanceof ServerException ) {
+			$status_code = $throwable->getCode() ? $throwable->getCode() : 400;
+		} elseif ( $throwable instanceof ServerException ) {
 			// `ServerException` uses HTTP status codes as exception codes, so we can rely on them.
 			$error_code  = $prefix . '_upstream_server_error';
-			$status_code = $e->getCode() ? $e->getCode() : 500;
-		} elseif ( $e instanceof TokenLimitReachedException ) {
+			$status_code = $throwable->getCode() ? $throwable->getCode() : 500;
+		} elseif ( $throwable instanceof TokenLimitReachedException ) {
 			$error_code  = $prefix . '_token_limit_reached';
 			$status_code = 400;
-		} elseif ( $e instanceof InvalidArgumentException ) {
+		} elseif ( $throwable instanceof InvalidArgumentException ) {
 			$error_code  = $prefix . '_invalid_argument';
 			$status_code = 400;
 		} else {
@@ -293,10 +293,10 @@
 
 		return new WP_Error(
 			$error_code,
-			$e->getMessage(),
+			$throwable->getMessage(),
 			array(
 				'status'          => $status_code,
-				'exception_class' => get_class( $e ),
+				'exception_class' => get_class( $throwable ),
 			)
 		);
 	}

Verified live

Applied this PR + the fix above to a test install and re-ran the same reproduction from the test report:

using_dimensions(array) -> NO FATAL, class: WP_AI_Client_Embedding_Builder (same instance: YES)
generate_embedding() after bad-type call -> WP_Error code=embedding_builder_error status=500 exception_class=TypeError

prompt using_temperature(array) -> NO FATAL, class: WP_AI_Client_Prompt_Builder
generate_text() after bad-type call -> WP_Error code=prompt_builder_error

no-provider generate_text() -> WP_Error code=prompt_invalid_argument   (unaffected, no regression)

Both WP_AI_Client_Prompt_Builder and WP_AI_Client_Embedding_Builder now degrade gracefully instead of fataling, and the existing no-provider error path is unchanged (no regression).

---

🤖 Generated with Claude Code

[JasonTheAdams]

I'm not sure why the tests are failing. They're working for me locally. Seems like there's something going on with the docker containers.

[jeffpaul]

Would love to get this in before Beta 1, can iterate from there if needed

[gziolo]

Looks good overall. Two non-blocking questions below about array inputs and SDK subclass compatibility.

[gziolo]

Does upstream guarantee compatibility for subclasses using the protected properties moved into ModelResolver? For example, assigning $this->model in a subclass previously selected the model, but generation now ignores that assignment. If this usage is supported, should upstream preserve it or document migration to usingModel()?

[JasonTheAdams]

Good catch. That was a backward-breaking change, though a deep and internal one. My inclination is that how it is now is "more right" in that it's closed by default. Since we're not subclassing this anywhere in core, and this was an undocumented part of the API, I think we're safe to continue.

[jorgefilipecosta]

With the new SDK events the event dispatcher now also fires wp_ai_client_before_generate_embedding and wp_ai_client_after_generate_embedding, but the list of hooks in the docblock of WP_AI_Client_Event_Dispatcher::dispatch still only mentions the generate_result ones

wordpress-develop/src/wp-includes/ai-client/adapters/class-wp-ai-client-event-dispatcher.php

Lines 47 to 52 in b47a0e4

	* In practice, the available action hook names are:
	*
	* - wp_ai_client_before_generate_result
	* - wp_ai_client_after_generate_result
	*
	* @since 7.0.0

. I guess we should add them there with a @since 7.2.0 note so they show up on the hooks reference.

[jorgefilipecosta]

Left some minor comments for consideration, but nothing is a blocker and things tested well.
I used the open ai connector (after setting a key) and then I used variations of this code to test:

<?php

add_action(
	'template_redirect',
	static function () {
		if ( is_admin() || wp_doing_ajax() || wp_doing_cron() || ( defined( 'REST_REQUEST' ) && REST_REQUEST ) ) {
			return;
		}

		header( 'Content-Type: text/plain; charset=utf-8' );


		$result = wp_ai_client_embedding( 'The quick brown fox', 'jumps over the lazy dog' )
			->using_provider_model( 'openai', 'text-embedding-3-small' )
			->using_dimensions( 256 )
			->generate_embedding_result();


		foreach ( $result->getEmbeddings() as $embedding ) {
			$vector = $embedding->getValues();  
			$size   = $embedding->getDimensions(); 
			var_dump( $size, count( $vector ), $vector );
		}
		var_dump( $result->getTokenUsage() );
		var_dump( $result->getModelMetadata()->getId() );
		die();
	}
);

I just loaded the site frontend and inspected the results.
In all the tests I did things worked as expected.

[github-actions]

A commit was made that fixes the Trac ticket referenced in the description of this pull request.

SVN changeset: 64327
GitHub commit: d6a40f4

This PR will be closed, but please confirm the accuracy of this and reopen if there is more work to be done.