AI: Add embedding generation support to WordPress

[extrachill]

PHP AI Client 1.4.0 introduces provider-agnostic embedding generation APIs, including a dedicated EmbeddingBuilder, embedding result DTOs, lifecycle events, and shared model resolution.

WordPress Core currently bundles PHP AI Client but does not expose embedding generation through its WordPress-facing AI API. Core should update the bundled library to 1.4.0 and add a native wrapper so plugins can use embedding-capable providers without coupling to a specific vendor SDK.

Embedding generation is a foundational primitive for semantic search, retrieval-augmented generation, recommendations, clustering, and knowledge bases built on WordPress. Vector storage, indexing, and retrieval remain separate concerns and are outside this ticket's scope.

Target: WordPress 7.1.

Proposed changes

• Update the bundled PHP AI Client library to 1.4.0.
• Introduce WP_AI_Client_Embedding_Builder, following the established WP_AI_Client_Prompt_Builder conventions.
• Expose a variadic wp_ai_client_embedding() entry point.
• Convert SDK exceptions into WP_Error values while preserving the fluent interface.
• Respect wp_supports_ai(), the existing default request-timeout filter, and an embedding-specific prevention filter.

Example:

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

Related

• PHP AI Client implementation: ​https://github.com/WordPress/php-ai-client/pull/244
• PHP AI Client 1.4.0 release: ​https://github.com/WordPress/php-ai-client/releases/tag/1.4.0
• WordPress Core implementation: ​https://github.com/WordPress/wordpress-develop/pull/12530

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.

Done! Thanks, @chubes4!

[jorbin]

The feature deadline is beta 1 and this request came in WAY to late in order for it to be considered. As such, I've bumped this to 7.2 so that it can be reviewed and given the proper consideration.

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.

[saadtajik]

📝 Test Report
Environment:

WordPress Playground

Method: Executed the new wp_ai_client_embedding() wrapper via a custom admin hook.

Testing Steps & Results:
I ran the proposed example code to verify the exposure of the new entry point and its exception-handling behavior in an unconfigured environment:

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

Entry Point Exposed: The wp_ai_client_embedding() function is correctly exposed and accessible without any fatal "undefined function" errors.

Graceful Exception Handling: Because my test environment lacked a configured AI provider/model, the underlying PHP AI Client threw an InvalidArgumentException.

WP_Error Conversion: As proposed in the PR, this SDK exception was successfully intercepted and converted into a clean WP_Error object:

Error Code: embedding_invalid_argument

Message: "No models found that support embedding_generation."

Exception Class Caught: WordPress\AiClient\Common\Exception\InvalidArgumentException

Verdict: ✅ Works as expected.
The wrapper safely prevents fatal crashes in environments without configured AI models and successfully converts SDK exceptions into standard WP_Error values. Great addition to Core!

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.