[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  declare (strict_types=1);
   4  namespace WordPress\AiClient\Tools\DTO;
   5  
   6  use WordPress\AiClient\Common\AbstractDataTransferObject;
   7  use WordPress\AiClient\Common\Exception\InvalidArgumentException;
   8  /**
   9   * Represents a response to a function call.
  10   *
  11   * This DTO encapsulates the result of executing a function that was
  12   * requested by the AI model through a FunctionCall.
  13   *
  14   * @since 0.1.0
  15   *
  16   * @phpstan-type FunctionResponseArrayShape array{id?: string, name?: string, response: mixed}
  17   *
  18   * @extends AbstractDataTransferObject<FunctionResponseArrayShape>
  19   */
  20  class FunctionResponse extends AbstractDataTransferObject
  21  {
  22      public const KEY_ID = 'id';
  23      public const KEY_NAME = 'name';
  24      public const KEY_RESPONSE = 'response';
  25      /**
  26       * @var string|null The ID of the function call this is responding to.
  27       */
  28      private ?string $id;
  29      /**
  30       * @var string|null The name of the function that was called.
  31       */
  32      private ?string $name;
  33      /**
  34       * @var mixed The response data from the function.
  35       */
  36      private $response;
  37      /**
  38       * Constructor.
  39       *
  40       * @since 0.1.0
  41       *
  42       * @param string|null $id The ID of the function call this is responding to.
  43       * @param string|null $name The name of the function that was called.
  44       * @param mixed $response The response data from the function.
  45       * @throws InvalidArgumentException If neither id nor name is provided.
  46       */
  47      public function __construct(?string $id, ?string $name, $response)
  48      {
  49          if ($id === null && $name === null) {
  50              throw new InvalidArgumentException('At least one of id or name must be provided.');
  51          }
  52          $this->id = $id;
  53          $this->name = $name;
  54          $this->response = $response;
  55      }
  56      /**
  57       * Gets the function call ID.
  58       *
  59       * @since 0.1.0
  60       *
  61       * @return string|null The function call ID.
  62       */
  63      public function getId(): ?string
  64      {
  65          return $this->id;
  66      }
  67      /**
  68       * Gets the function name.
  69       *
  70       * @since 0.1.0
  71       *
  72       * @return string|null The function name.
  73       */
  74      public function getName(): ?string
  75      {
  76          return $this->name;
  77      }
  78      /**
  79       * Gets the function response.
  80       *
  81       * @since 0.1.0
  82       *
  83       * @return mixed The response data.
  84       */
  85      public function getResponse()
  86      {
  87          return $this->response;
  88      }
  89      /**
  90       * {@inheritDoc}
  91       *
  92       * @since 0.1.0
  93       */
  94      public static function getJsonSchema(): array
  95      {
  96          return ['type' => 'object', 'properties' => [self::KEY_ID => ['type' => 'string', 'description' => 'The ID of the function call this is responding to.'], self::KEY_NAME => ['type' => 'string', 'description' => 'The name of the function that was called.'], self::KEY_RESPONSE => ['type' => ['string', 'number', 'boolean', 'object', 'array', 'null'], 'description' => 'The response data from the function.']], 'anyOf' => [['required' => [self::KEY_RESPONSE, self::KEY_ID]], ['required' => [self::KEY_RESPONSE, self::KEY_NAME]]]];
  97      }
  98      /**
  99       * {@inheritDoc}
 100       *
 101       * @since 0.1.0
 102       *
 103       * @return FunctionResponseArrayShape
 104       */
 105      public function toArray(): array
 106      {
 107          $data = [];
 108          if ($this->id !== null) {
 109              $data[self::KEY_ID] = $this->id;
 110          }
 111          if ($this->name !== null) {
 112              $data[self::KEY_NAME] = $this->name;
 113          }
 114          $data[self::KEY_RESPONSE] = $this->response;
 115          return $data;
 116      }
 117      /**
 118       * {@inheritDoc}
 119       *
 120       * @since 0.1.0
 121       */
 122      public static function fromArray(array $array): self
 123      {
 124          static::validateFromArrayData($array, [self::KEY_RESPONSE]);
 125          return new self($array[self::KEY_ID] ?? null, $array[self::KEY_NAME] ?? null, $array[self::KEY_RESPONSE]);
 126      }
 127  }