Download the PHP package wordpress/php-ai-client without Composer

PHP AI Client

Part of the AI Building Blocks for WordPress initiative

A provider agnostic PHP AI client SDK to communicate with any generative AI models of various capabilities using a uniform API.

General information

This project is a PHP SDK, which can be installed as a Composer package. In WordPress, it could be bundled in plugins. It is however not a plugin itself.

While this project is stewarded by WordPress AI Team members and contributors, it is technically WordPress agnostic. The gap the project addresses is relevant for not only the WordPress ecosystem, but the overall PHP ecosystem, so any PHP project could benefit from it. There is also no technical reason to scope it to WordPress, as communicating with AI models and their providers is independent of WordPress's built-in APIs and paradigms.

Installation

Code examples

Text generation using a specific model

Text generation using any compatible model from a specific provider

Text generation using any compatible model

Text generation with additional parameters

Text generation with multiple candidates using any compatible model

Text generation using max tokens

Image generation using any compatible model

Embedding generation using a specific model

Unlike the other capabilities, embedding generation always requires you to name the model. Embedding vectors are only comparable to other vectors produced by the same model, so a stored set of embeddings is permanently tied to the model that created it. If the library picked a model for you, that choice could change between requests — for example when the registered providers change — silently making new vectors incomparable to the ones you already stored. Omitting the model therefore raises an error rather than falling back to a default.

You can also pass a model instance, which is useful when you already have one or want to reference the provider class directly:

Batch embedding generation

Embedding generation with dimensions

Embedding inputs are independent MessagePart values, not a conversation. input() accepts one input or a list of inputs. Variadic withInput() accepts one or more arguments, and lists can be passed using PHP's spread syntax (withInput(...$inputs)). Each input may be a string, MessagePart, File, or message-part array shape.

The model you name is verified before any request is sent: it must support embedding generation, accept the input modalities of your inputs, and support every configuration option you set. If it does not, an InvalidArgumentException explains which capability or option is unsupported. To check without triggering an exception, call isSupported(), which returns false for any model that cannot fulfill the request — including one whose provider is not registered or configured, or a model ID the provider does not offer. Only omitting the model entirely still throws, since that is a programming error rather than an unsupported model.

Discovering available embedding models

Since no model is chosen for you, you may need to find out which embedding models the configured providers offer:

See the PromptBuilder class and the EmbeddingBuilder class and their public methods for all the ways you can configure generation.

More documentation is coming soon.

Event Dispatching

The AI Client supports PSR-14 event dispatching for prompt lifecycle events. This allows you to hook into the generation process for logging, monitoring, or other integrations.

Available Events

• BeforeGenerateResultEvent - Dispatched before a prompt is sent to the model
• AfterGenerateResultEvent - Dispatched after a result is received from the model
• BeforeGenerateEmbeddingEvent - Dispatched before embedding inputs are sent to the model
• AfterGenerateEmbeddingEvent - Dispatched after an embedding result is received from the model

Important: Event listeners should not return a value, as they will be ignored. In order to modify data that is passed with the event object, you need to rely on setters on the event object. Any event data for which there are no setters on the event object is meant to be immutable or, in other words, read-only for the event listener.

Connecting Your Event Dispatcher

To enable event dispatching, pass any PSR-14 compatible EventDispatcherInterface to the client:

Example: Logging Events

Further reading

For more information on the requirements and guiding principles, please review:

• Glossary
• Requirements
• Architecture
• Prepublish Checklist

See the contributing documentation for more information on how to get involved.