[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, parameter schema, and optional annotations.
  12   *
  13   * @since 0.1.0
  14   *
  15   * @phpstan-type FunctionDeclarationArrayShape array{
  16   *     name: string,
  17   *     description: string,
  18   *     parameters?: array<string, mixed>,
  19   *     annotations?: array<string, mixed>
  20   * }
  21   *
  22   * @extends AbstractDataTransferObject<FunctionDeclarationArrayShape>
  23   */
  24  class FunctionDeclaration extends AbstractDataTransferObject
  25  {
  26      public const KEY_NAME = 'name';
  27      public const KEY_DESCRIPTION = 'description';
  28      public const KEY_PARAMETERS = 'parameters';
  29      public const KEY_ANNOTATIONS = 'annotations';
  30      /**
  31       * @var string The name of the function.
  32       */
  33      private string $name;
  34      /**
  35       * @var string A description of what the function does.
  36       */
  37      private string $description;
  38      /**
  39       * @var array<string, mixed>|null The JSON schema for the function parameters.
  40       */
  41      private ?array $parameters;
  42      /**
  43       * @var array<string, mixed> Open-ended annotations which may be consumed by Providers.
  44       */
  45      private array $annotations;
  46      /**
  47       * Constructor.
  48       *
  49       * @since 0.1.0
  50       * @since 1.5.0 Adds the optional $annotations parameter.
  51       *
  52       * @param string $name The name of the function.
  53       * @param string $description A description of what the function does.
  54       * @param array<string, mixed>|null $parameters The JSON schema for the function parameters.
  55       * @param array<string, mixed> $annotations Optional annotations with JSON-serializable values.
  56       */
  57      public function __construct(string $name, string $description, ?array $parameters = null, array $annotations = [])
  58      {
  59          $this->name = $name;
  60          $this->description = $description;
  61          $this->parameters = $parameters;
  62          $this->annotations = $annotations;
  63      }
  64      /**
  65       * Gets the function name.
  66       *
  67       * @since 0.1.0
  68       *
  69       * @return string The function name.
  70       */
  71      public function getName(): string
  72      {
  73          return $this->name;
  74      }
  75      /**
  76       * Gets the function description.
  77       *
  78       * @since 0.1.0
  79       *
  80       * @return string The function description.
  81       */
  82      public function getDescription(): string
  83      {
  84          return $this->description;
  85      }
  86      /**
  87       * Gets the function parameters schema.
  88       *
  89       * @since 0.1.0
  90       *
  91       * @return array<string, mixed>|null The parameters schema.
  92       */
  93      public function getParameters(): ?array
  94      {
  95          return $this->parameters;
  96      }
  97      /**
  98       * Gets the function annotations.
  99       *
 100       * @since 1.5.0
 101       *
 102       * @return array<string, mixed> The annotations, or an empty array if none were provided.
 103       */
 104      public function getAnnotations(): array
 105      {
 106          return $this->annotations;
 107      }
 108      /**
 109       * {@inheritDoc}
 110       *
 111       * @since 0.1.0
 112       */
 113      public static function getJsonSchema(): array
 114      {
 115          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], self::KEY_ANNOTATIONS => ['type' => 'object', 'description' => 'Optional annotations interpreted by consumers.', 'additionalProperties' => \true]], 'required' => [self::KEY_NAME, self::KEY_DESCRIPTION]];
 116      }
 117      /**
 118       * {@inheritDoc}
 119       *
 120       * @since 0.1.0
 121       *
 122       * @return FunctionDeclarationArrayShape
 123       */
 124      public function toArray(): array
 125      {
 126          $data = [self::KEY_NAME => $this->name, self::KEY_DESCRIPTION => $this->description];
 127          if ($this->parameters !== null) {
 128              $data[self::KEY_PARAMETERS] = $this->parameters;
 129          }
 130          if ($this->annotations !== []) {
 131              $data[self::KEY_ANNOTATIONS] = $this->annotations;
 132          }
 133          return $data;
 134      }
 135      /**
 136       * {@inheritDoc}
 137       *
 138       * @since 0.1.0
 139       */
 140      public static function fromArray(array $array): self
 141      {
 142          static::validateFromArrayData($array, [self::KEY_NAME, self::KEY_DESCRIPTION]);
 143          return new self($array[self::KEY_NAME], $array[self::KEY_DESCRIPTION], $array[self::KEY_PARAMETERS] ?? null, $array[self::KEY_ANNOTATIONS] ?? []);
 144      }
 145  }