[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  declare (strict_types=1);
   4  namespace WordPress\AiClient\Results\DTO;
   5  
   6  use WordPress\AiClient\Common\AbstractDataTransferObject;
   7  use WordPress\AiClient\Common\Exception\InvalidArgumentException;
   8  use WordPress\AiClient\Providers\DTO\ProviderMetadata;
   9  use WordPress\AiClient\Providers\Models\DTO\ModelMetadata;
  10  use WordPress\AiClient\Results\Contracts\ResultInterface;
  11  /**
  12   * Represents the result of an embedding generation operation.
  13   *
  14   * @since 1.4.0
  15   *
  16   * @phpstan-import-type TokenUsageArrayShape from TokenUsage
  17   * @phpstan-import-type ProviderMetadataArrayShape from ProviderMetadata
  18   * @phpstan-import-type ModelMetadataArrayShape from ModelMetadata
  19   * @phpstan-import-type EmbeddingList from Embedding
  20   *
  21   * @phpstan-type EmbeddingResultArrayShape array{
  22   *     id: string,
  23   *     embeddings: list<EmbeddingList>,
  24   *     dimensions: int,
  25   *     tokenUsage: TokenUsageArrayShape,
  26   *     providerMetadata: ProviderMetadataArrayShape,
  27   *     modelMetadata: ModelMetadataArrayShape,
  28   *     additionalData?: array<string, mixed>
  29   * }
  30   *
  31   * @extends AbstractDataTransferObject<EmbeddingResultArrayShape>
  32   */
  33  class EmbeddingResult extends AbstractDataTransferObject implements ResultInterface
  34  {
  35      public const KEY_ID = 'id';
  36      public const KEY_EMBEDDINGS = 'embeddings';
  37      public const KEY_DIMENSIONS = 'dimensions';
  38      public const KEY_TOKEN_USAGE = 'tokenUsage';
  39      public const KEY_PROVIDER_METADATA = 'providerMetadata';
  40      public const KEY_MODEL_METADATA = 'modelMetadata';
  41      public const KEY_ADDITIONAL_DATA = 'additionalData';
  42      /**
  43       * @var string Unique identifier for this result.
  44       */
  45      private string $id;
  46      /**
  47       * @var list<Embedding>
  48       */
  49      private array $embeddings;
  50      /**
  51       * @var int The vector dimension count.
  52       */
  53      private int $dimensions;
  54      /**
  55       * @var TokenUsage Token usage statistics.
  56       */
  57      private \WordPress\AiClient\Results\DTO\TokenUsage $tokenUsage;
  58      /**
  59       * @var ProviderMetadata Provider metadata.
  60       */
  61      private ProviderMetadata $providerMetadata;
  62      /**
  63       * @var ModelMetadata Model metadata.
  64       */
  65      private ModelMetadata $modelMetadata;
  66      /**
  67       * @var array<string, mixed>
  68       */
  69      private array $additionalData;
  70      /**
  71       * Constructor.
  72       *
  73       * @since 1.4.0
  74       *
  75       * @param string $id Unique identifier for this result.
  76       * @param list<Embedding|EmbeddingList> $embeddings The generated embedding vectors.
  77       * @param int $dimensions The vector dimension count.
  78       * @param TokenUsage $tokenUsage Token usage statistics.
  79       * @param ProviderMetadata $providerMetadata Provider metadata.
  80       * @param ModelMetadata $modelMetadata Model metadata.
  81       * @param array<string, mixed> $additionalData Additional data.
  82       */
  83      public function __construct(string $id, array $embeddings, int $dimensions, \WordPress\AiClient\Results\DTO\TokenUsage $tokenUsage, ProviderMetadata $providerMetadata, ModelMetadata $modelMetadata, array $additionalData = [])
  84      {
  85          if (empty($embeddings)) {
  86              throw new InvalidArgumentException('At least one embedding must be provided');
  87          }
  88          if ($dimensions < 1) {
  89              throw new InvalidArgumentException('Embedding dimensions must be greater than zero');
  90          }
  91          $normalizedEmbeddings = [];
  92          foreach ($embeddings as $embedding) {
  93              if (!$embedding instanceof \WordPress\AiClient\Results\DTO\Embedding) {
  94                  $embedding = new \WordPress\AiClient\Results\DTO\Embedding($embedding, $dimensions);
  95              } elseif ($embedding->getDimensions() !== $dimensions) {
  96                  throw new InvalidArgumentException('Embedding vector length must match dimensions.');
  97              }
  98              $normalizedEmbeddings[] = $embedding;
  99          }
 100          $this->id = $id;
 101          $this->embeddings = $normalizedEmbeddings;
 102          $this->dimensions = $dimensions;
 103          $this->tokenUsage = $tokenUsage;
 104          $this->providerMetadata = $providerMetadata;
 105          $this->modelMetadata = $modelMetadata;
 106          $this->additionalData = $additionalData;
 107      }
 108      /**
 109       * {@inheritDoc}
 110       *
 111       * @since 1.4.0
 112       */
 113      public function getId(): string
 114      {
 115          return $this->id;
 116      }
 117      /**
 118       * Gets the generated embedding vectors.
 119       *
 120       * @since 1.4.0
 121       *
 122       * @return list<Embedding> The embeddings.
 123       */
 124      public function getEmbeddings(): array
 125      {
 126          return $this->embeddings;
 127      }
 128      /**
 129       * Gets the first generated embedding vector.
 130       *
 131       * @since 1.4.0
 132       *
 133       * @return Embedding The first embedding.
 134       */
 135      public function getEmbedding(): \WordPress\AiClient\Results\DTO\Embedding
 136      {
 137          return $this->embeddings[0];
 138      }
 139      /**
 140       * Gets the vector dimension count.
 141       *
 142       * @since 1.4.0
 143       *
 144       * @return int The vector dimension count.
 145       */
 146      public function getDimensions(): int
 147      {
 148          return $this->dimensions;
 149      }
 150      /**
 151       * {@inheritDoc}
 152       *
 153       * @since 1.4.0
 154       */
 155      public function getTokenUsage(): \WordPress\AiClient\Results\DTO\TokenUsage
 156      {
 157          return $this->tokenUsage;
 158      }
 159      /**
 160       * {@inheritDoc}
 161       *
 162       * @since 1.4.0
 163       */
 164      public function getProviderMetadata(): ProviderMetadata
 165      {
 166          return $this->providerMetadata;
 167      }
 168      /**
 169       * {@inheritDoc}
 170       *
 171       * @since 1.4.0
 172       */
 173      public function getModelMetadata(): ModelMetadata
 174      {
 175          return $this->modelMetadata;
 176      }
 177      /**
 178       * {@inheritDoc}
 179       *
 180       * @since 1.4.0
 181       */
 182      public function getAdditionalData(): array
 183      {
 184          return $this->additionalData;
 185      }
 186      /**
 187       * Gets the JSON schema for embedding results.
 188       *
 189       * @since 1.4.0
 190       *
 191       * @return array<string, mixed> The JSON schema.
 192       */
 193      public static function getJsonSchema(): array
 194      {
 195          return ['type' => 'object', 'properties' => [self::KEY_ID => ['type' => 'string', 'description' => 'Unique identifier for this result.'], self::KEY_EMBEDDINGS => ['type' => 'array', 'items' => \WordPress\AiClient\Results\DTO\Embedding::getJsonSchema(), 'description' => 'Generated embedding vectors.'], self::KEY_DIMENSIONS => ['type' => 'integer', 'minimum' => 1, 'description' => 'Embedding vector dimensions.'], self::KEY_TOKEN_USAGE => \WordPress\AiClient\Results\DTO\TokenUsage::getJsonSchema(), self::KEY_PROVIDER_METADATA => ProviderMetadata::getJsonSchema(), self::KEY_MODEL_METADATA => ModelMetadata::getJsonSchema(), self::KEY_ADDITIONAL_DATA => ['type' => 'object', 'additionalProperties' => \true, 'description' => 'Additional provider-specific data.']], 'required' => [self::KEY_ID, self::KEY_EMBEDDINGS, self::KEY_DIMENSIONS, self::KEY_TOKEN_USAGE, self::KEY_PROVIDER_METADATA, self::KEY_MODEL_METADATA]];
 196      }
 197      /**
 198       * Converts the embedding result to an array.
 199       *
 200       * @since 1.4.0
 201       *
 202       * @return EmbeddingResultArrayShape The embedding result array.
 203       */
 204      public function toArray(): array
 205      {
 206          $data = [self::KEY_ID => $this->id, self::KEY_EMBEDDINGS => array_map(static fn(\WordPress\AiClient\Results\DTO\Embedding $embedding): array => $embedding->toArray(), $this->embeddings), self::KEY_DIMENSIONS => $this->dimensions, self::KEY_TOKEN_USAGE => $this->tokenUsage->toArray(), self::KEY_PROVIDER_METADATA => $this->providerMetadata->toArray(), self::KEY_MODEL_METADATA => $this->modelMetadata->toArray()];
 207          if (!empty($this->additionalData)) {
 208              $data[self::KEY_ADDITIONAL_DATA] = $this->additionalData;
 209          }
 210          return $data;
 211      }
 212      /**
 213       * Creates an embedding result from an array.
 214       *
 215       * @since 1.4.0
 216       *
 217       * @param EmbeddingResultArrayShape $array The embedding result array.
 218       * @return self The embedding result instance.
 219       */
 220      public static function fromArray(array $array): self
 221      {
 222          static::validateFromArrayData($array, [self::KEY_ID, self::KEY_EMBEDDINGS, self::KEY_DIMENSIONS, self::KEY_TOKEN_USAGE, self::KEY_PROVIDER_METADATA, self::KEY_MODEL_METADATA]);
 223          return new self($array[self::KEY_ID], $array[self::KEY_EMBEDDINGS], $array[self::KEY_DIMENSIONS], \WordPress\AiClient\Results\DTO\TokenUsage::fromArray($array[self::KEY_TOKEN_USAGE]), ProviderMetadata::fromArray($array[self::KEY_PROVIDER_METADATA]), ModelMetadata::fromArray($array[self::KEY_MODEL_METADATA]), $array[self::KEY_ADDITIONAL_DATA] ?? []);
 224      }
 225  }