[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  declare (strict_types=1);
   4  namespace WordPress\AiClient\Results\DTO;
   5  
   6  use ArrayIterator;
   7  use Countable;
   8  use IteratorAggregate;
   9  use JsonSerializable;
  10  use Traversable;
  11  use WordPress\AiClient\Common\Exception\InvalidArgumentException;
  12  /**
  13   * Represents a single generated embedding vector.
  14   *
  15   * @since 1.4.0
  16   *
  17   * @phpstan-type EmbeddingList list<float|int>
  18   *
  19   * @implements IteratorAggregate<int, float|int>
  20   */
  21  final class Embedding implements Countable, IteratorAggregate, JsonSerializable
  22  {
  23      /**
  24       * @var EmbeddingList
  25       */
  26      private array $values;
  27      /**
  28       * @var int The vector dimension count.
  29       */
  30      private int $dimensions;
  31      /**
  32       * Constructor.
  33       *
  34       * @since 1.4.0
  35       *
  36       * @param EmbeddingList $values The embedding vector values.
  37       * @param int $dimensions The vector dimension count.
  38       */
  39      public function __construct(array $values, int $dimensions)
  40      {
  41          if ($dimensions < 1) {
  42              throw new InvalidArgumentException('Embedding dimensions must be greater than zero');
  43          }
  44          if (!self::isEmbeddingList($values)) {
  45              if (!array_is_list($values)) {
  46                  throw new InvalidArgumentException('Embedding values must be a list array.');
  47              }
  48              throw new InvalidArgumentException('Embedding values must be integers or floats.');
  49          }
  50          if (count($values) !== $dimensions) {
  51              throw new InvalidArgumentException('Embedding vector length must match dimensions.');
  52          }
  53          $this->values = $values;
  54          $this->dimensions = $dimensions;
  55      }
  56      /**
  57       * Checks whether the value is a list of integers or floats.
  58       *
  59       * @since 1.4.0
  60       *
  61       * @param mixed $values The value to check.
  62       * @return bool True if the value is an embedding list.
  63       *
  64       * @phpstan-assert-if-true EmbeddingList $values
  65       */
  66      private static function isEmbeddingList($values): bool
  67      {
  68          if (!is_array($values) || !array_is_list($values)) {
  69              return \false;
  70          }
  71          foreach ($values as $value) {
  72              if (!is_int($value) && !is_float($value)) {
  73                  return \false;
  74              }
  75          }
  76          return \true;
  77      }
  78      /**
  79       * Gets the vector values.
  80       *
  81       * @since 1.4.0
  82       *
  83       * @return EmbeddingList The embedding vector values.
  84       */
  85      public function getValues(): array
  86      {
  87          return $this->values;
  88      }
  89      /**
  90       * Gets the vector dimension count.
  91       *
  92       * @since 1.4.0
  93       *
  94       * @return int The vector dimension count.
  95       */
  96      public function getDimensions(): int
  97      {
  98          return $this->dimensions;
  99      }
 100      /**
 101       * Gets the number of vector values.
 102       *
 103       * @since 1.4.0
 104       *
 105       * @return int The number of vector values.
 106       */
 107      public function count(): int
 108      {
 109          return $this->dimensions;
 110      }
 111      /**
 112       * Gets an iterator for the vector values.
 113       *
 114       * @since 1.4.0
 115       *
 116       * @return Traversable<int, float|int> The vector value iterator.
 117       */
 118      public function getIterator(): Traversable
 119      {
 120          return new ArrayIterator($this->values);
 121      }
 122      /**
 123       * Gets the JSON schema for embedding vectors.
 124       *
 125       * @since 1.4.0
 126       *
 127       * @return array<string, mixed> The JSON schema.
 128       */
 129      public static function getJsonSchema(): array
 130      {
 131          return ['type' => 'array', 'items' => ['type' => 'number'], 'description' => 'Generated embedding vector values.'];
 132      }
 133      /**
 134       * Converts the embedding to an array.
 135       *
 136       * @since 1.4.0
 137       *
 138       * @return EmbeddingList The embedding vector values.
 139       */
 140      public function toArray(): array
 141      {
 142          return $this->values;
 143      }
 144      /**
 145       * Creates an embedding from an array.
 146       *
 147       * @since 1.4.0
 148       *
 149       * @param EmbeddingList $array The embedding vector values.
 150       * @param int $dimensions The vector dimension count.
 151       * @return self The embedding instance.
 152       */
 153      public static function fromArray(array $array, int $dimensions): self
 154      {
 155          return new self($array, $dimensions);
 156      }
 157      /**
 158       * Converts the embedding to a JSON-serializable value.
 159       *
 160       * @since 1.4.0
 161       *
 162       * @return EmbeddingList The embedding vector values.
 163       */
 164      public function jsonSerialize(): array
 165      {
 166          return $this->toArray();
 167      }
 168  }