[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\Messages\DTO\Message;
   9  use WordPress\AiClient\Results\Enums\FinishReasonEnum;
  10  /**
  11   * Represents a candidate response from an AI model.
  12   *
  13   * When generating content, AI models can produce multiple candidates.
  14   * Each candidate contains a message and metadata about why generation stopped.
  15   *
  16   * @since 0.1.0
  17   *
  18   * @phpstan-import-type MessageArrayShape from Message
  19   *
  20   * @phpstan-type CandidateArrayShape array{message: MessageArrayShape, finishReason: string}
  21   *
  22   * @extends AbstractDataTransferObject<CandidateArrayShape>
  23   */
  24  class Candidate extends AbstractDataTransferObject
  25  {
  26      public const KEY_MESSAGE = 'message';
  27      public const KEY_FINISH_REASON = 'finishReason';
  28      /**
  29       * @var Message The generated message.
  30       */
  31      private Message $message;
  32      /**
  33       * @var FinishReasonEnum The reason generation stopped.
  34       */
  35      private FinishReasonEnum $finishReason;
  36      /**
  37       * Constructor.
  38       *
  39       * @since 0.1.0
  40       *
  41       * @param Message $message The generated message.
  42       * @param FinishReasonEnum $finishReason The reason generation stopped.
  43       */
  44      public function __construct(Message $message, FinishReasonEnum $finishReason)
  45      {
  46          if (!$message->getRole()->isModel()) {
  47              throw new InvalidArgumentException('Message must be a model message.');
  48          }
  49          $this->message = $message;
  50          $this->finishReason = $finishReason;
  51      }
  52      /**
  53       * Gets the generated message.
  54       *
  55       * @since 0.1.0
  56       *
  57       * @return Message The message.
  58       */
  59      public function getMessage(): Message
  60      {
  61          return $this->message;
  62      }
  63      /**
  64       * Gets the finish reason.
  65       *
  66       * @since 0.1.0
  67       *
  68       * @return FinishReasonEnum The finish reason.
  69       */
  70      public function getFinishReason(): FinishReasonEnum
  71      {
  72          return $this->finishReason;
  73      }
  74      /**
  75       * {@inheritDoc}
  76       *
  77       * @since 0.1.0
  78       */
  79      public static function getJsonSchema(): array
  80      {
  81          return ['type' => 'object', 'properties' => [self::KEY_MESSAGE => Message::getJsonSchema(), self::KEY_FINISH_REASON => ['type' => 'string', 'enum' => FinishReasonEnum::getValues(), 'description' => 'The reason generation stopped.']], 'required' => [self::KEY_MESSAGE, self::KEY_FINISH_REASON]];
  82      }
  83      /**
  84       * {@inheritDoc}
  85       *
  86       * @since 0.1.0
  87       *
  88       * @return CandidateArrayShape
  89       */
  90      public function toArray(): array
  91      {
  92          return [self::KEY_MESSAGE => $this->message->toArray(), self::KEY_FINISH_REASON => $this->finishReason->value];
  93      }
  94      /**
  95       * {@inheritDoc}
  96       *
  97       * @since 0.1.0
  98       */
  99      public static function fromArray(array $array): self
 100      {
 101          static::validateFromArrayData($array, [self::KEY_MESSAGE, self::KEY_FINISH_REASON]);
 102          $messageData = $array[self::KEY_MESSAGE];
 103          return new self(Message::fromArray($messageData), FinishReasonEnum::from($array[self::KEY_FINISH_REASON]));
 104      }
 105      /**
 106       * Performs a deep clone of the candidate.
 107       *
 108       * This method ensures that the message object is cloned to prevent
 109       * modifications to the cloned candidate from affecting the original.
 110       *
 111       * @since 0.4.2
 112       */
 113      public function __clone()
 114      {
 115          $this->message = clone $this->message;
 116      }
 117  }