[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  declare (strict_types=1);
   4  namespace WordPress\AiClient\Providers\Models\DTO;
   5  
   6  use WordPress\AiClient\Common\AbstractDataTransferObject;
   7  use WordPress\AiClient\Common\Exception\InvalidArgumentException;
   8  use WordPress\AiClient\Providers\Models\Enums\CapabilityEnum;
   9  /**
  10   * Represents metadata about an AI model.
  11   *
  12   * This class contains information about a specific AI model, including
  13   * its identifier, display name, supported capabilities, and configuration options.
  14   *
  15   * @since 0.1.0
  16   *
  17   * @phpstan-import-type SupportedOptionArrayShape from SupportedOption
  18   *
  19   * @phpstan-type ModelMetadataArrayShape array{
  20   *     id: string,
  21   *     name: string,
  22   *     supportedCapabilities: list<string>,
  23   *     supportedOptions: list<SupportedOptionArrayShape>
  24   * }
  25   *
  26   * @extends AbstractDataTransferObject<ModelMetadataArrayShape>
  27   */
  28  class ModelMetadata extends AbstractDataTransferObject
  29  {
  30      public const KEY_ID = 'id';
  31      public const KEY_NAME = 'name';
  32      public const KEY_SUPPORTED_CAPABILITIES = 'supportedCapabilities';
  33      public const KEY_SUPPORTED_OPTIONS = 'supportedOptions';
  34      /**
  35       * @var string The model's unique identifier.
  36       */
  37      protected string $id;
  38      /**
  39       * @var string The model's display name.
  40       */
  41      protected string $name;
  42      /**
  43       * @var list<CapabilityEnum> The model's supported capabilities.
  44       */
  45      protected array $supportedCapabilities;
  46      /**
  47       * @var list<SupportedOption> The model's supported configuration options.
  48       */
  49      protected array $supportedOptions;
  50      /**
  51       * Constructor.
  52       *
  53       * @since 0.1.0
  54       *
  55       * @param string $id The model's unique identifier.
  56       * @param string $name The model's display name.
  57       * @param list<CapabilityEnum> $supportedCapabilities The model's supported capabilities.
  58       * @param list<SupportedOption> $supportedOptions The model's supported configuration options.
  59       *
  60       * @throws InvalidArgumentException If arrays are not lists.
  61       */
  62      public function __construct(string $id, string $name, array $supportedCapabilities, array $supportedOptions)
  63      {
  64          if (!array_is_list($supportedCapabilities)) {
  65              throw new InvalidArgumentException('Supported capabilities must be a list array.');
  66          }
  67          if (!array_is_list($supportedOptions)) {
  68              throw new InvalidArgumentException('Supported options must be a list array.');
  69          }
  70          $this->id = $id;
  71          $this->name = $name;
  72          $this->supportedCapabilities = $supportedCapabilities;
  73          $this->supportedOptions = $supportedOptions;
  74      }
  75      /**
  76       * Gets the model's unique identifier.
  77       *
  78       * @since 0.1.0
  79       *
  80       * @return string The model ID.
  81       */
  82      public function getId(): string
  83      {
  84          return $this->id;
  85      }
  86      /**
  87       * Gets the model's display name.
  88       *
  89       * @since 0.1.0
  90       *
  91       * @return string The model name.
  92       */
  93      public function getName(): string
  94      {
  95          return $this->name;
  96      }
  97      /**
  98       * Gets the model's supported capabilities.
  99       *
 100       * @since 0.1.0
 101       *
 102       * @return list<CapabilityEnum> The supported capabilities.
 103       */
 104      public function getSupportedCapabilities(): array
 105      {
 106          return $this->supportedCapabilities;
 107      }
 108      /**
 109       * Gets the model's supported configuration options.
 110       *
 111       * @since 0.1.0
 112       *
 113       * @return list<SupportedOption> The supported options.
 114       */
 115      public function getSupportedOptions(): array
 116      {
 117          return $this->supportedOptions;
 118      }
 119      /**
 120       * {@inheritDoc}
 121       *
 122       * @since 0.1.0
 123       */
 124      public static function getJsonSchema(): array
 125      {
 126          return ['type' => 'object', 'properties' => [self::KEY_ID => ['type' => 'string', 'description' => 'The model\'s unique identifier.'], self::KEY_NAME => ['type' => 'string', 'description' => 'The model\'s display name.'], self::KEY_SUPPORTED_CAPABILITIES => ['type' => 'array', 'items' => ['type' => 'string', 'enum' => CapabilityEnum::getValues()], 'description' => 'The model\'s supported capabilities.'], self::KEY_SUPPORTED_OPTIONS => ['type' => 'array', 'items' => \WordPress\AiClient\Providers\Models\DTO\SupportedOption::getJsonSchema(), 'description' => 'The model\'s supported configuration options.']], 'required' => [self::KEY_ID, self::KEY_NAME, self::KEY_SUPPORTED_CAPABILITIES, self::KEY_SUPPORTED_OPTIONS]];
 127      }
 128      /**
 129       * {@inheritDoc}
 130       *
 131       * @since 0.1.0
 132       *
 133       * @return ModelMetadataArrayShape
 134       */
 135      public function toArray(): array
 136      {
 137          return [self::KEY_ID => $this->id, self::KEY_NAME => $this->name, self::KEY_SUPPORTED_CAPABILITIES => array_map(static fn(CapabilityEnum $capability): string => $capability->value, $this->supportedCapabilities), self::KEY_SUPPORTED_OPTIONS => array_map(static fn(\WordPress\AiClient\Providers\Models\DTO\SupportedOption $option): array => $option->toArray(), $this->supportedOptions)];
 138      }
 139      /**
 140       * {@inheritDoc}
 141       *
 142       * @since 0.1.0
 143       */
 144      public static function fromArray(array $array): self
 145      {
 146          static::validateFromArrayData($array, [self::KEY_ID, self::KEY_NAME, self::KEY_SUPPORTED_CAPABILITIES, self::KEY_SUPPORTED_OPTIONS]);
 147          return new self($array[self::KEY_ID], $array[self::KEY_NAME], array_map(static fn(string $capability): CapabilityEnum => CapabilityEnum::from($capability), $array[self::KEY_SUPPORTED_CAPABILITIES]), array_map(static fn(array $optionData): \WordPress\AiClient\Providers\Models\DTO\SupportedOption => \WordPress\AiClient\Providers\Models\DTO\SupportedOption::fromArray($optionData), $array[self::KEY_SUPPORTED_OPTIONS]));
 148      }
 149      /**
 150       * Performs a deep clone of the model metadata.
 151       *
 152       * This method ensures that supported option objects are cloned to prevent
 153       * modifications to the cloned metadata from affecting the original.
 154       *
 155       * @since 0.4.2
 156       */
 157      public function __clone()
 158      {
 159          $clonedOptions = [];
 160          foreach ($this->supportedOptions as $option) {
 161              $clonedOptions[] = clone $option;
 162          }
 163          $this->supportedOptions = $clonedOptions;
 164      }
 165  }