[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * WP AI Client: WP_AI_Client_Embedding_Builder class
   4   *
   5   * @package WordPress
   6   * @subpackage AI
   7   * @since 7.2.0
   8   */
   9  
  10  use WordPress\AiClient\AiClient;
  11  use WordPress\AiClient\Builders\EmbeddingBuilder;
  12  use WordPress\AiClient\Providers\Http\DTO\RequestOptions;
  13  use WordPress\AiClient\Providers\Models\Contracts\ModelInterface;
  14  use WordPress\AiClient\Providers\Models\DTO\ModelConfig;
  15  use WordPress\AiClient\Providers\ProviderRegistry;
  16  use WordPress\AiClient\Results\DTO\Embedding;
  17  use WordPress\AiClient\Results\DTO\EmbeddingResult;
  18  
  19  /**
  20   * Fluent builder for generating embeddings, returning WP_Error on failure.
  21   *
  22   * This class provides a fluent interface for generating embedding vectors from
  23   * text or file inputs. It wraps the PHP AI Client SDK's EmbeddingBuilder and
  24   * adds WordPress-specific behavior including WP_Error handling instead of
  25   * exceptions and snake_case method naming.
  26   *
  27   * A model must be specified via `using_model()` or `using_provider_model()`.
  28   * Embedding vectors are only comparable to other vectors produced by the same
  29   * model, so no model is selected automatically.
  30   *
  31   * Only the generating methods will return a WP_Error, to not break the fluent
  32   * interface. As soon as any exception is caught in a chain of method calls,
  33   * the returned instance will be in an error state, and all subsequent method
  34   * calls will be no-ops that just return the same error state instance. Only
  35   * when a generating method is called, the WP_Error will be returned. The
  36   * support check methods are the exception to the no-op behavior: they return
  37   * false rather than the error state instance.
  38   *
  39   * @since 7.2.0
  40   *
  41   * @see WP_AI_Client_Builder
  42   *
  43   * @phpstan-import-type EmbeddingInput from EmbeddingBuilder
  44   *
  45   * @method self with_input(...$input) Adds one or more inputs to embed.
  46   * @method self using_dimensions(int $dimensions) Sets the embedding dimensions.
  47   * @method self using_model(ModelInterface $model) Sets the model to use for generation.
  48   * @method self using_provider_model(string $providerIdOrClassName, string $modelId) Sets the model to use for generation, by provider and model identifier.
  49   * @method self using_model_config(ModelConfig $config) Sets the model configuration.
  50   * @method self using_request_options(RequestOptions $options) Sets the request options for HTTP transport.
  51   * @method bool is_supported() Checks whether the specified model supports the current inputs and configuration.
  52   * @method EmbeddingResult|WP_Error generate_embedding_result() Generates an embedding result from the configured inputs.
  53   * @method Embedding|WP_Error generate_embedding() Generates a single embedding from the configured input.
  54   * @method list<Embedding>|WP_Error generate_embeddings() Generates embeddings from the configured inputs.
  55   */
  56  class WP_AI_Client_Embedding_Builder extends WP_AI_Client_Builder {
  57  
  58      /**
  59       * List of methods that generate embeddings from the inputs.
  60       *
  61       * Structured as a map for faster lookups.
  62       *
  63       * @since 7.2.0
  64       * @var array<string, bool>
  65       */
  66      private static array $generating_methods = array(
  67          'generate_embedding_result' => true,
  68          'generate_embedding'        => true,
  69          'generate_embeddings'       => true,
  70      );
  71  
  72      /**
  73       * List of methods that check whether the embedding generation is supported.
  74       *
  75       * Structured as a map for faster lookups.
  76       *
  77       * @since 7.2.0
  78       * @var array<string, bool>
  79       */
  80      private static array $support_check_methods = array(
  81          'is_supported' => true,
  82      );
  83  
  84      /**
  85       * Creates the wrapped embedding builder instance from the PHP AI Client SDK.
  86       *
  87       * @since 7.2.0
  88       *
  89       * @param ProviderRegistry                         $registry The provider registry for finding suitable models.
  90       * @param EmbeddingInput|list<EmbeddingInput>|null $input    Initial input(s) to embed, or null.
  91       *                                                           A string for simple text inputs,
  92       *                                                           a MessagePart or File object for
  93       *                                                           structured content, an array for a
  94       *                                                           message part array shape, or a list
  95       *                                                           of any of these to embed multiple
  96       *                                                           inputs.
  97       * @return EmbeddingBuilder The SDK embedding builder instance.
  98       */
  99  	protected function create_sdk_builder( ProviderRegistry $registry, $input ): object {
 100          return new EmbeddingBuilder( $registry, $input, AiClient::getEventDispatcher() );
 101      }
 102  
 103      /**
 104       * Retrieves the prefix used for WP_Error codes created by this builder.
 105       *
 106       * @since 7.2.0
 107       *
 108       * @return string The error code prefix.
 109       */
 110  	protected function get_error_code_prefix(): string {
 111          return 'embedding';
 112      }
 113  
 114      /**
 115       * Retrieves the error message to use when the embedding generation is prevented by a filter.
 116       *
 117       * @since 7.2.0
 118       *
 119       * @return string The translated error message.
 120       */
 121  	protected function get_prevented_error_message(): string {
 122          return __( 'Embedding generation was prevented by a filter.' );
 123      }
 124  
 125      /**
 126       * Checks whether the embedding generation is prevented by the `wp_ai_client_prevent_embedding` filter.
 127       *
 128       * @since 7.2.0
 129       *
 130       * @return bool Whether the embedding generation is prevented.
 131       */
 132  	protected function is_prevented_by_filter(): bool {
 133          /**
 134           * Filters whether to prevent the embedding generation from being executed.
 135           *
 136           * @since 7.2.0
 137           *
 138           * @param bool                           $prevent Whether to prevent the embedding generation. Default false.
 139           * @param WP_AI_Client_Embedding_Builder $builder A clone of the embedding builder instance (read-only).
 140           */
 141          return (bool) apply_filters( 'wp_ai_client_prevent_embedding', false, clone $this );
 142      }
 143  
 144      /**
 145       * Retrieves the methods that generate embeddings from the inputs.
 146       *
 147       * @since 7.2.0
 148       *
 149       * @return array<string, bool> The generating methods map.
 150       */
 151  	protected function get_generating_methods(): array {
 152          return self::$generating_methods;
 153      }
 154  
 155      /**
 156       * Retrieves the methods that check whether the embedding generation is supported.
 157       *
 158       * @since 7.2.0
 159       *
 160       * @return array<string, bool> The support check methods map.
 161       */
 162  	protected function get_support_check_methods(): array {
 163          return self::$support_check_methods;
 164      }
 165  }