[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 function call request from an AI model.
  10   *
  11   * This DTO encapsulates information about a function that the AI model
  12   * wants to invoke, including the function name and its arguments.
  13   *
  14   * @since 0.1.0
  15   *
  16   * @phpstan-type FunctionCallArrayShape array{id?: string, name?: string, args?: mixed}
  17   *
  18   * @extends AbstractDataTransferObject<FunctionCallArrayShape>
  19   */
  20  class FunctionCall extends AbstractDataTransferObject
  21  {
  22      public const KEY_ID = 'id';
  23      public const KEY_NAME = 'name';
  24      public const KEY_ARGS = 'args';
  25      /**
  26       * @var string|null Unique identifier for this function call.
  27       */
  28      private ?string $id;
  29      /**
  30       * @var string|null The name of the function to call.
  31       */
  32      private ?string $name;
  33      /**
  34       * @var mixed The arguments to pass to the function.
  35       */
  36      private $args;
  37      /**
  38       * Constructor.
  39       *
  40       * @since 0.1.0
  41       *
  42       * @param string|null $id Unique identifier for this function call.
  43       * @param string|null $name The name of the function to call.
  44       * @param mixed $args The arguments to pass to the function.
  45       * @throws InvalidArgumentException If neither id nor name is provided.
  46       */
  47      public function __construct(?string $id = null, ?string $name = null, $args = null)
  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->args = $args;
  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 arguments.
  80       *
  81       * @since 0.1.0
  82       *
  83       * @return mixed The function arguments.
  84       */
  85      public function getArgs()
  86      {
  87          return $this->args;
  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' => 'Unique identifier for this function call.'], self::KEY_NAME => ['type' => 'string', 'description' => 'The name of the function to call.'], self::KEY_ARGS => ['type' => ['string', 'number', 'boolean', 'object', 'array', 'null'], 'description' => 'The arguments to pass to the function.']], 'anyOf' => [['required' => [self::KEY_ID]], ['required' => [self::KEY_NAME]]]];
  97      }
  98      /**
  99       * {@inheritDoc}
 100       *
 101       * @since 0.1.0
 102       *
 103       * @return FunctionCallArrayShape
 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          if ($this->args !== null) {
 115              $data[self::KEY_ARGS] = $this->args;
 116          }
 117          return $data;
 118      }
 119      /**
 120       * {@inheritDoc}
 121       *
 122       * @since 0.1.0
 123       */
 124      public static function fromArray(array $array): self
 125      {
 126          return new self($array[self::KEY_ID] ?? null, $array[self::KEY_NAME] ?? null, $array[self::KEY_ARGS] ?? null);
 127      }
 128  }