AI: Update PHP AI Client to 1.4.0 and introduce WP_AI_Client_Embedding_Builder by JasonTheAdams · Pull Request #12530 · WordPress/wordpress-develop · GitHub

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 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.

Regenerated via `bash tools/php-ai-client/installer.sh --version=1.4.0`. The 1.4.0 release adds embedding generation support, including the new EmbeddingBuilder, embedding lifecycle events, Embedding/EmbeddingResult DTOs, and a shared ModelResolver for model selection. Full changelog: https://github.com/WordPress/php-ai-client/releases/tag/1.4.0 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Wraps the PHP AI Client SDK's new EmbeddingBuilder (added in 1.4.0), following the same pattern as WP_AI_Client_Prompt_Builder: snake_case method naming via __call() proxying, and WP_Error handling instead of exceptions, with an error state that preserves the fluent interface. Introduces the wp_ai_client_embedding() entry point function and the wp_ai_client_prevent_embedding filter, analogous to their prompt counterparts. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

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.

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

Props jason_the_adams, dkotter, extrachill, gziolo.

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

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.

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

In 1.4.0, model selection state (model, registry, providerIdOrClassName, requestOptions) moved from the SDK's PromptBuilder onto its ModelResolver. Update the reflection helper to fall back to the model resolver for properties that no longer live on the wrapped builder. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…ass. WP_AI_Client_Prompt_Builder and WP_AI_Client_Embedding_Builder shared nearly all of their machinery: the snake_case __call() proxying, the WP_Error error-state handling, exception-to-WP_Error conversion, and the default request timeout setup. Move that into an abstract WP_AI_Client_Builder base class, parameterized via abstract methods for the SDK builder instantiation, error code prefix, prevent filter, and generating/support-check method maps. No behavior changes: error codes, filter names, and _doing_it_wrong notices (which continue to report the concrete class name) are identical to before. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

… filter. Allows developers to adjust the default request timeout per builder type, e.g. a different timeout for embeddings than for prompts. The builder's class name is passed as the second filter parameter. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…edding(). Covers the WordPress wrapper behavior (not the SDK itself): constructor input parsing and the default request timeout handling, snake_case fluent proxying and error-state semantics, the wp_supports_ai() and wp_ai_client_prevent_embedding gates, exception-to-WP_Error mapping with embedding-prefixed error codes, generation through a mock embedding model, and the variadic input handling of wp_ai_client_embedding(). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

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.

Done! Thanks, @chubes4!

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()

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.

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.

JasonTheAdams and others added 2 commits July 14, 2026 20:07

dkotter reviewed Jul 15, 2026

View reviewed changes

Comment thread src/wp-includes/ai-client/class-wp-ai-client-embedding-builder.php Outdated

Comment thread src/wp-includes/ai-client/class-wp-ai-client-embedding-builder.php Outdated

JasonTheAdams and others added 4 commits July 14, 2026 22:03

henryperkins mentioned this pull request Jul 15, 2026

Reject non-finite values in embedding vectors WordPress/php-ai-client#263

Open

dkotter approved these changes Jul 15, 2026

View reviewed changes

dkotter mentioned this pull request Jul 23, 2026

Bring over embeddings support from the PHP AI Client WordPress/ai#892

Merged

AI: Update PHP AI Client to 1.4.0 and introduce WP_AI_Client_Embedding_Builder by JasonTheAdams · Pull Request #12530 · WordPress/wordpress-develop · GitHub

Uh oh!

AI: Update PHP AI Client to 1.4.0 and introduce WP_AI_Client_Embedding_Builder - #12530

AI: Update PHP AI Client to 1.4.0 and introduce WP_AI_Client_Embedding_Builder#12530
JasonTheAdams wants to merge 6 commits into
WordPress:trunkfrom
JasonTheAdams:update/php-ai-client-1.4.0

JasonTheAdams commented Jul 15, 2026 •
edited
Loading

Uh oh!

Uh oh!

github-actions Bot commented Jul 15, 2026 •
edited
Loading

Uh oh!

Uh oh!

github-actions Bot commented Jul 15, 2026

Uh oh!

dkotter left a comment

Uh oh!

Uh oh!

Uh oh!

chubes4 commented Jul 15, 2026

Uh oh!

JasonTheAdams commented Jul 15, 2026

Uh oh!

dkotter left a comment

Uh oh!

JasonTheAdams commented Jul 15, 2026

Uh oh!

gziolo commented Aug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

AI: Update PHP AI Client to 1.4.0 and introduce WP_AI_Client_Embedding_Builder by JasonTheAdams · Pull Request #12530 · WordPress/wordpress-develop · GitHub

Uh oh!

AI: Update PHP AI Client to 1.4.0 and introduce WP_AI_Client_Embedding_Builder - #12530

Conversation

JasonTheAdams commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Library update

New: WP_AI_Client_Embedding_Builder

Testing

Shared base class: WP_AI_Client_Builder

Test updates

Uh oh!

github-actions Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 15, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

dkotter left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

chubes4 commented Jul 15, 2026

Uh oh!

JasonTheAdams commented Jul 15, 2026

Uh oh!

dkotter left a comment

Choose a reason for hiding this comment

Uh oh!

JasonTheAdams commented Jul 15, 2026

Uh oh!

gziolo commented Aug 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

JasonTheAdams commented Jul 15, 2026 •
edited
Loading

github-actions Bot commented Jul 15, 2026 •
edited
Loading