[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  /**
   8   * Represents a function declaration for AI models.
   9   *
  10   * This DTO describes a function that can be called by the AI model,
  11   * including its name, description, and parameter schema.
  12   *
  13   * @since 0.1.0
  14   *
  15   * @phpstan-type FunctionDeclarationArrayShape array{
  16   *     name: string,
  17   *     description: string,
  18   *     parameters?: array<string, mixed>
  19   * }
  20   *
  21   * @extends AbstractDataTransferObject<FunctionDeclarationArrayShape>
  22   */
  23  class FunctionDeclaration extends AbstractDataTransferObject
  24  {
  25      public const KEY_NAME = 'name';
  26      public const KEY_DESCRIPTION = 'description';
  27      public const KEY_PARAMETERS = 'parameters';
  28      /**
  29       * @var string The name of the function.
  30       */
  31      private string $name;
  32      /**
  33       * @var string A description of what the function does.
  34       */
  35      private string $description;
  36      /**
  37       * @var array<string, mixed>|null The JSON schema for the function parameters.
  38       */
  39      private ?array $parameters;
  40      /**
  41       * Constructor.
  42       *
  43       * @since 0.1.0
  44       *
  45       * @param string $name The name of the function.
  46       * @param string $description A description of what the function does.
  47       * @param array<string, mixed>|null $parameters The JSON schema for the function parameters.
  48       */
  49      public function __construct(string $name, string $description, ?array $parameters = null)
  50      {
  51          $this->name = $name;
  52          $this->description = $description;
  53          $this->parameters = $parameters;
  54      }
  55      /**
  56       * Gets the function name.
  57       *
  58       * @since 0.1.0
  59       *
  60       * @return string The function name.
  61       */
  62      public function getName(): string
  63      {
  64          return $this->name;
  65      }
  66      /**
  67       * Gets the function description.
  68       *
  69       * @since 0.1.0
  70       *
  71       * @return string The function description.
  72       */
  73      public function getDescription(): string
  74      {
  75          return $this->description;
  76      }
  77      /**
  78       * Gets the function parameters schema.
  79       *
  80       * @since 0.1.0
  81       *
  82       * @return array<string, mixed>|null The parameters schema.
  83       */
  84      public function getParameters(): ?array
  85      {
  86          return $this->parameters;
  87      }
  88      /**
  89       * {@inheritDoc}
  90       *
  91       * @since 0.1.0
  92       */
  93      public static function getJsonSchema(): array
  94      {
  95          return ['type' => 'object', 'properties' => [self::KEY_NAME => ['type' => 'string', 'description' => 'The name of the function.'], self::KEY_DESCRIPTION => ['type' => 'string', 'description' => 'A description of what the function does.'], self::KEY_PARAMETERS => ['type' => 'object', 'description' => 'The JSON schema for the function parameters.', 'additionalProperties' => \true]], 'required' => [self::KEY_NAME, self::KEY_DESCRIPTION]];
  96      }
  97      /**
  98       * {@inheritDoc}
  99       *
 100       * @since 0.1.0
 101       *
 102       * @return FunctionDeclarationArrayShape
 103       */
 104      public function toArray(): array
 105      {
 106          $data = [self::KEY_NAME => $this->name, self::KEY_DESCRIPTION => $this->description];
 107          if ($this->parameters !== null) {
 108              $data[self::KEY_PARAMETERS] = $this->parameters;
 109          }
 110          return $data;
 111      }
 112      /**
 113       * {@inheritDoc}
 114       *
 115       * @since 0.1.0
 116       */
 117      public static function fromArray(array $array): self
 118      {
 119          static::validateFromArrayData($array, [self::KEY_NAME, self::KEY_DESCRIPTION]);
 120          return new self($array[self::KEY_NAME], $array[self::KEY_DESCRIPTION], $array[self::KEY_PARAMETERS] ?? null);
 121      }
 122  }